Πώς να ενσωματώσετε βίντεο HLS στον ιστότοπό σας (iframe και hls.js)

Το HLS (HTTP Live Streaming) είναι η μορφή που χρησιμοποιούν σήμερα οι περισσότεροι ιστότοποι για βίντεο κατ' απαίτηση. Αντί για ένα τεράστιο αρχείο MP4, το βίντεο περιγράφεται από μια μικρή λίστα αναπαραγωγής σε μορφή κειμένου που δείχνει σε διάφορες εκδοχές του ίδιου βίντεο, κομμένες η καθεμία σε σύντομα τμήματα. Ο player κατεβάζει μερικά τμήματα εκ των προτέρων, μετρά πόσο γρήγορα φτάνουν και αλλάζει εκδοχή εν κινήσει. Οι θεατές με σύνδεση κινητού παίρνουν μια ελαφριά εκδοχή, οι θεατές με οπτική ίνα την πιο ευκρινή, και κανείς δεν περιμένει να κατέβει ολόκληρο αρχείο πριν εμφανιστεί το πρώτο καρέ.

Αυτός ο οδηγός δείχνει δύο τρόπους να βάλετε ένα βίντεο HLS από το UFOLOAD στη δική σας ιστοσελίδα: τον έτοιμο player σε iframe, που παίρνει περίπου ένα λεπτό, και το δικό σας στοιχείο <video> με hls.js, που σας δίνει πλήρη έλεγχο της σελίδας. Και οι δύο χρησιμοποιούν την ίδια ροή, οπότε μπορείτε να ξεκινήσετε με το iframe και να περάσετε αργότερα στο hls.js χωρίς να ανεβάσετε τίποτα ξανά.

Πώς είναι μια ροή HLS από το UFOLOAD

Αφού ανεβάσετε ένα αρχείο, ο converter το κωδικοποιεί με βίντεο H.264 και στερεοφωνικό ήχο AAC σε μία έως τέσσερις εκδοχές (renditions): 360p, 720p, 1080p και 2160p (4K). Μια εκδοχή δεν είναι ποτέ μεγαλύτερη από την πηγή σας, οπότε ένα ανέβασμα 720p παράγει 720p και 360p, ποτέ ένα αναβαθμισμένο 1080p. Η υψηλότερη εκδοχή που παίρνετε στην πράξη εξαρτάται επίσης από το πρόγραμμά σας· η σελίδα τιμών απαριθμεί τα τρέχοντα όρια. Αν θέλετε όλο το υπόβαθρο για το πώς επιλέγονται οι βαθμίδες, διαβάστε το άρθρο κλίμακες προσαρμοστικού bitrate.

Κάθε εκδοχή αποθηκεύεται ως κανονικό MP4 με το ευρετήριο στην αρχή του αρχείου. Όταν ένας θεατής ξεκινά την αναπαραγωγή, το επίπεδο αποθήκευσης πακετάρει αυτά τα αρχεία MP4 σε HLS εν κινήσει: μια κύρια λίστα αναπαραγωγής (master.m3u8) απαριθμεί κάθε εκδοχή με το bitrate αιχμής, την ανάλυση και τους codecs της, και κάθε εκδοχή έχει τη δική της λίστα αναπαραγωγής με τμήματα τεσσάρων δευτερολέπτων. Τα keyframes τοποθετούνται ώστε να ευθυγραμμίζονται με τα όρια των τμημάτων, και αυτό επιτρέπει στον player να αλλάζει ποιότητα καθαρά στη μέση ενός βίντεο.

Η λίστα αναπαραγωγής και τα τμήματα σερβίρονται από κόμβους cache με κεφαλίδα Access-Control-Allow-Origin: *, ώστε ένας player που τρέχει στο domain σας να μπορεί να τα ζητά απευθείας. Κάθε URL είναι υπογεγραμμένο και έχει χρόνο λήξης, κάτι που θα έχει σημασία αργότερα, όταν θα μιλήσουμε για την προσέγγιση με hls.js.

Βήμα 1: ανεβάστε το βίντεο και περιμένετε να είναι έτοιμο

Ανεβάστε από τον πίνακα ελέγχου σύροντας το αρχείο ή επικολλώντας έναν άμεσο σύνδεσμο, ή χρησιμοποιήστε FTP, WebDAV ή το API (δείτε ανέβασμα βίντεο μέσω API για παραδείγματα σε curl, Python και Node.js). Ένα αρχείο περνά από τις καταστάσεις uploading, queued, processing και ready· η κατάσταση failed αναφέρεται μαζί με τον λόγο και μπορείτε να ξαναδοκιμάσετε από τον πίνακα ελέγχου. Τα σύντομα κλιπ είναι έτοιμα μέσα σε λίγα λεπτά, οι μεγάλες ταινίες χρειάζονται περισσότερο και τα επί πληρωμή προγράμματα έχουν ουρά κωδικοποίησης προτεραιότητας.

Δεν χρειάζεται να περιμένετε για να ολοκληρώσετε τη σελίδα. Αν κάποιος ανοίξει τον player ενώ το αρχείο ακόμη επεξεργάζεται, εμφανίζεται ειδοποίηση επεξεργασίας με την πρόοδο και ο player περνά μόνος του στο βίντεο όταν τελειώσει η επεξεργασία. Ωστόσο, ελέγξτε ότι η κατάσταση είναι ready πριν δημοσιεύσετε τη σελίδα, ώστε οι πρώτοι επισκέπτες να μη δουν μια μπάρα προόδου.

Θα χρειαστείτε το αναγνωριστικό του βίντεο. Ο πίνακας ελέγχου το δείχνει στο πάνελ κοινοποίησης και το API το επιστρέφει ως public_id, έναν σύντομο κωδικό 11 χαρακτήρων. Αυτός ο κωδικός μπαίνει στη διεύθυνση ενσωμάτωσης.

Βήμα 2: ενσωματώστε τον player με iframe

Ο πίνακας ελέγχου δίνει ένα απόσπασμα iframe αμέσως μετά το ανέβασμα και στο πάνελ κοινοποίησης κάθε βίντεο. Μοιάζει με το πρώτο μπλοκ παρακάτω. Αντικαταστήστε το VIDEO_ID με το αναγνωριστικό του βίντεό σας. Η ίδια η σελίδα του player δεν ευρετηριάζεται από τις μηχανές αναζήτησης, κάτι που θέλετε σε μια ενσωμάτωση: κατατάσσεται η δική σας σελίδα, όχι το frame του player.

<iframe width="640" height="360"
  src="https://iframe.andromedans.live/e/VIDEO_ID"
  title="My video"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen></iframe>

Τα σταθερά μεγέθη σε pixel χαλάνε στα κινητά. Για responsive σελίδα, τυλίξτε το iframe σε ένα πλαίσιο που διατηρεί την αναλογία 16:9 και αφήστε το frame να το γεμίσει. Ο player γεμίζει ολόκληρο το frame, οπότε το βίντεο κλιμακώνεται σωστά.

<div style="position:relative;aspect-ratio:16/9;max-width:960px">
  <iframe src="https://iframe.andromedans.live/e/VIDEO_ID"
    title="My video"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture"
    allowfullscreen></iframe>
</div>

Παράμετροι που μπορείτε να προσθέσετε στη διεύθυνση

• Το autoplay=1 ξεκινά την αναπαραγωγή όταν φορτώνει ο player. Οι browsers στις περισσότερες περιπτώσεις μπλοκάρουν την αυτόματη αναπαραγωγή με ήχο, γι' αυτό συνδυάστε το με mute=1.
• Το mute=1 ξεκινά το βίντεο σε σίγαση· ο θεατής μπορεί να ενεργοποιήσει τον ήχο οποιαδήποτε στιγμή.
• Το loop=1 ξεκινά το βίντεο από την αρχή όταν τελειώσει.
• Το t=30 ξεκινά την αναπαραγωγή από το 30ό δευτερόλεπτο, χρήσιμο για συνδέσμους σε μια συγκεκριμένη στιγμή ενός μεγαλύτερου βίντεο.

Μια παράμετρος στη διεύθυνση υπερισχύει πάντα της ίδιας ρύθμισης στο Player studio. Χρησιμοποιήστε το Player studio για προεπιλογές που ισχύουν παντού, όπως το skin, το χρώμα έμφασης, το λογότυπο και τη διάταξη των κουμπιών, και τις παραμέτρους όταν μια σελίδα πρέπει να συμπεριφέρεται διαφορετικά. Μπορείτε ακόμη να έχετε ξεχωριστό προφίλ player για κάθε domain ενσωμάτωσης.

Βήμα 3 (προαιρετικό): παίξτε τη ροή με hls.js

Το iframe είναι ο συντομότερος δρόμος, αλλά μερικές φορές θέλετε δικό σας κώδικα: δική σας μπάρα χειριστηρίων, το βίντεο μέσα σε carousel, γεγονότα analytics από τον δικό σας κώδικα. Τότε χρειάζεστε τη διεύθυνση της λίστας αναπαραγωγής και μια βιβλιοθήκη player. Οι browsers εκτός του Safari δεν μπορούν να παίξουν HLS εγγενώς, οπότε η συνηθισμένη επιλογή είναι το hls.js, μια βιβλιοθήκη JavaScript που τροφοδοτεί τμήματα HLS σε ένα τυπικό στοιχείο <video>. Το Safari και το iOS παίζουν HLS εγγενώς και δεν το χρειάζονται.

Η διεύθυνση της λίστας αναπαραγωγής είναι το πεδίο links.playback του αντικειμένου βίντεο. Ζητήστε τη από τον διακομιστή σας με κλειδί API, γιατί το κλειδί δεν πρέπει ποτέ να εμφανίζεται σε κώδικα του browser. Η ίδια κλήση επιστρέφει το links.expires_at και οι σύνδεσμοι είναι υπογεγραμμένοι και περιορισμένης διάρκειας, οπότε ζητάτε νέο σύνδεσμο κάθε φορά που αποδίδετε τη σελίδα αντί να τον αποθηκεύετε στη βάση δεδομένων σας.

const BASE = 'https://ufoload.com/api/v1'

export async function playbackUrl(fileId) {
  const res = await fetch(`${BASE}/files/${fileId}`, {
    headers: { Authorization: `Bearer ${process.env.UFOLOAD_API_KEY}` },
  })
  if (!res.ok) throw new Error(`UFOLOAD API: ${res.status}`)
  const { file, links } = await res.json()
  if (file.status !== 'ready') return null // still processing
  return links.playback // signed master.m3u8 URL
}

Αν χρειάζεστε διάρκεια ισχύος διαφορετική από την προεπιλεγμένη, το POST /files/{id}/links δέχεται ttl από 60 δευτερόλεπτα έως 30 ημέρες και μπορεί να δέσει τον σύνδεσμο σε διεύθυνση IP ή σε cookie. Η τεκμηρίωση API το καλύπτει πλήρως. Υπάρχει επίσης ένα δημόσιο endpoint, το GET /api/v1/public/files/{id}, που δεν χρειάζεται κλειδί· το χρησιμοποιούν οι σελίδες προβολής και ενσωμάτωσης και οι σύνδεσμοί του ισχύουν για έξι ώρες.

Στη σελίδα, δημιουργήστε τον player. Το παρακάτω μπλοκ χρησιμοποιεί hls.js όπου υποστηρίζεται, περνά σε εγγενή αναπαραγωγή στο Safari και αλλιώς δείχνει ένα απλό μήνυμα. Φιλοξενήστε μόνοι σας το αρχείο της βιβλιοθήκης ή καρφιτσώστε μια έκδοση αντί να φορτώνετε ό,τι είναι πιο πρόσφατο.

<video id="player" controls playsinline preload="metadata"
       poster="POSTER_URL" style="width:100%;aspect-ratio:16/9;background:#000"></video>
<script src="/vendor/hls.min.js"></script>
<script>
  const video = document.getElementById('player')
  const src = 'PLAYLIST_URL_FROM_YOUR_SERVER'

  if (window.Hls && Hls.isSupported()) {
    const hls = new Hls()
    hls.loadSource(src)
    hls.attachMedia(video)
    hls.on(Hls.Events.ERROR, (_, data) => {
      if (!data.fatal) return
      if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad()
      else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError()
      else hls.destroy()
    })
  } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src // Safari, iOS
  } else {
    video.outerHTML = '<p>This browser cannot play HLS video.</p>'
  }
</script>

Το αντικείμενο βίντεο περιέχει επίσης το links.poster για την εικόνα εξωφύλλου και το links.sprite για μικρογραφίες προεπισκόπησης με hover, που μπορείτε να χρησιμοποιήσετε αν φτιάξετε τη δική σας μπάρα αναζήτησης. Με το hls.js παραιτείστε από όσα κάνει για εσάς ο player του UFOLOAD: το μενού ποιότητας, τα κεφάλαια, την επιλογή υποτίτλων, το λογότυπο σε επικάλυψη και, όταν υπάρχουν διαθέσιμες διαφημίσεις, τις διαφημίσεις. Αυτό είναι το πραγματικό αντίτιμο και ο παρακάτω πίνακας το συνοψίζει.

iframe ή hls.js: ποιο να χρησιμοποιήσετε

Λίστα ελέγχου αντιμετώπισης προβλημάτων

• Μαύρο καρέ ή ατελείωτο εικονίδιο φόρτωσης. Ανοίξτε τον πίνακα δικτύου του browser και αναζητήστε το master.m3u8. Ένα 403 σημαίνει ότι ο σύνδεσμος έληξε ή ότι ο θεατής αποκλείεται από κανόνα χώρας ή IP· ζητήστε νέο σύνδεσμο.
• Μπλοκάρεται από τον browser σε σελίδα HTTPS. Όλα πρέπει να είναι HTTPS. Μην επικολλάτε ποτέ διεύθυνση http:// στο iframe ή στο hls.js.
• Η αυτόματη αναπαραγωγή δεν κάνει τίποτα. Οι browsers μπλοκάρουν την αυτόματη αναπαραγωγή με ήχο. Προσθέστε mute=1 ή, στο hls.js, ορίστε video.muted = true πριν καλέσετε το play().
• Ειδοποίηση επεξεργασίας αντί για βίντεο. Το αρχείο δεν είναι ακόμη έτοιμο. Ελέγχετε περιοδικά το GET /files/{id} μέχρι το status να γίνει ready.
• Παίζει μόνο χαμηλή ποιότητα. Ο player ξεκινά συντηρητικά και ανεβαίνει μόλις μετρήσει τη διαμεταγωγή. Το πρόγραμμά σας και η πηγή σας περιορίζουν επίσης την ανώτερη εκδοχή· συγκρίνετε με τις τιμές και τη σελίδα δυνατοτήτων.

Μόλις η σελίδα σας λειτουργεί, ίσως θελήσετε να την προστατεύσετε από hotlinking ή, όταν υπάρχουν διαθέσιμες διαφημίσεις, να βγάλετε έσοδα από αυτήν. Και τα δύο καλύπτονται στους επόμενους οδηγούς: περιορίστε πού μπορεί να ενσωματωθεί το βίντεό σας και βγάλτε έσοδα από τον ιστότοπο βίντεο με διαφημίσεις στον player. Αν ακόμη αποφασίζετε πού θα φιλοξενήσετε, η λίστα ελέγχου για φιλοξενία βίντεο απαριθμεί τι να συγκρίνετε.