HLSKit

Quand vous écoutez un podcast ou regardez une vidéo en streaming, il y a un protocole derrière que vous ne voyez jamais : HLS. HTTP Live Streaming, inventé par Apple en 2009, devenu le standard de facto pour la diffusion audio et vidéo sur le web. Votre navigateur, votre téléphone, votre Apple TV — tout parle HLS.

Le principe est simple : on découpe un fichier média en petits segments de quelques secondes, on écrit un manifeste (un fichier .m3u8) qui liste ces segments dans l'ordre, et le lecteur les télécharge un par un via HTTP. Pas de serveur spécialisé, pas de protocole exotique — du HTTP standard, avec tout ce qui va bien : CDN, cache, HTTPS.

En travaillant sur PodcastFeedMaker et l'infrastructure serveur PodcastFeedVapor, un besoin évident est apparu : gérer les fichiers média eux-mêmes. Pas juste les métadonnées RSS, mais les vrais fichiers audio et vidéo — les découper, les encoder, les chiffrer, les valider. Le tout depuis du Swift pur, sans dépendance externe dans le cœur de la lib, compatible macOS, iOS, et Linux.

J'ai cherché une lib Swift qui faisait ça. Aucune n'existait. Des wrappers FFmpeg, oui. Des lecteurs HLS, oui. Mais un pipeline complet — du parsing de manifestes au chiffrement des segments en passant par le transcodage cloud — en Swift natif ? Rien.

HLSKit est née de ce vide.

La première version couvrait le pipeline VOD de bout en bout : parsing, génération, segmentation, transcodage, chiffrement. La deuxième a ajouté le transcodage cloud — Cloudflare, AWS, Mux. Mais il manquait la pièce la plus ambitieuse : le live. Pas un placeholder, pas un wrapper — un vrai pipeline temps réel capable de prendre un flux audio ou vidéo, de l'encoder, le segmenter, le diffuser, et le servir en Low-Latency HLS avec push multi-destination. C'est ce que fait HLSKit 0.3.0.

Avant de plonger dans la lib, un détour rapide sur le protocole pour ceux qui n'ont jamais touché à HLS. Si vous connaissez déjà, sautez à la section suivante.

HLS fonctionne en trois étapes. D'abord, on prend un fichier média (MP4, MOV, audio…) et on le segmente — on le découpe en morceaux de 4 à 10 secondes. Chaque morceau est un fichier indépendant, téléchargeable par HTTP.

Ensuite, on écrit un manifeste — un fichier texte avec l'extension .m3u8 — qui liste les segments dans l'ordre avec leur durée. C'est le plan de route du lecteur.

Enfin, pour le multi-qualité (adaptive bitrate), on crée un master playlist qui pointe vers plusieurs media playlists : une pour la 360p, une pour la 720p, une pour la 1080p. Le lecteur choisit automatiquement la qualité selon la bande passante disponible.

En live, le principe est le même — mais les segments sont produits en temps réel au lieu d'être pré-découpés. Le manifeste est mis à jour à chaque nouveau segment, et les anciens sortent d'une fenêtre glissante. Low-Latency HLS va encore plus loin : les segments sont découpés en parties plus petites et le lecteur peut les demander avant même que le segment complet soit terminé.

Ce fichier texte de 6 lignes, c'est un master playlist HLS. Chaque STREAM-INF décrit une variante : bande passante, résolution, codecs. Le lecteur lit ce fichier, évalue sa connexion, et charge la bonne playlist. C'est aussi simple que ça — et c'est aussi complexe que ça quand on veut le faire proprement, parce que la RFC 8216 qui spécifie HLS fait 50 pages de règles très précises.

HLSKit couvre le pipeline HLS de bout en bout — VOD et live. Pas juste un bout — tout le chemin, du fichier source au segment chiffré prêt à être servi, ou du flux micro jusqu'au CDN en temps réel. Le tout en Swift pur, Sendable de bout en bout, avec zéro dépendance externe dans la lib core.

HLSEngine est la façade qui orchestre les opérations VOD. En quelques lignes, vous parsez un manifeste, validez sa conformité, et segmentez un fichier. Pas de config complexe, pas de boilerplate :

Trois opérations, trois lignes de code chacune. Le parser retourne des modèles Swift typés. Le validateur retourne un rapport structuré. Le segmenteur retourne les segments, la playlist générée, et le segment d'initialisation. Pas de strings magiques, pas de casting — du Swift idiomatique.

C'est la grande nouveauté de la 0.3.0. LivePipeline orchestre un flux temps réel complet : une source média (micro, caméra, fichier) alimente un encodeur, qui produit des frames encodées, qui sont segmentées à la volée, assemblées dans une playlist mise à jour en continu, et poussées vers une ou plusieurs destinations.

Le tout est composable. Chaque étape du pipeline est un composant indépendant injecté via LivePipelineComponents — vous assemblez exactement ce dont vous avez besoin.

Le pipeline émet des événements (LivePipelineEvent) et des statistiques temps réel (LivePipelineStatistics) via des AsyncStream. Vous pouvez surveiller le nombre de segments produits, le bitrate réel, la santé du buffer, le nombre de frames encodées par seconde — tout ça en temps réel, sans polling.

La machine à états (LivePipelineState) gère les transitions : idle → starting → running → stopping → stopped. Un LivePipelineSummary est produit à l'arrêt avec la durée totale, le nombre de segments, les bytes écrits.

Pour simplifier le démarrage, LivePipelineConfiguration propose des presets préconfigurés pour les cas d'usage courants. Chaque preset règle l'encodage, la segmentation, la playlist et les options spécifiques au scénario :

Audio :

Vidéo :

Pro — Spatial Audio, HDR, DRM, Accessibilité :

HLS classique a une latence de 15 à 30 secondes — le temps d'accumuler plusieurs segments complets. Low-Latency HLS (LL-HLS) réduit ça à moins de 2 secondes en découpant les segments en parties plus petites (PartialSegment) et en permettant au lecteur de les demander avant la fin du segment.

HLSKit implémente la spec LL-HLS complète. Le LLHLSManager orchestre la production de partial segments en cours de production et annonce les capacités serveur (CAN-BLOCK-RELOAD, PART-HOLD-BACK). Le BlockingPlaylistHandler gère le CAN-BLOCK-RELOAD — le lecteur fait une requête "bloquante" et le serveur ne répond que quand le prochain morceau est prêt. Le DeltaUpdateGenerator produit des playlists delta (EXT-X-SKIP) pour réduire la bande passante des rafraîchissements.

La beauté du système, c'est que LL-HLS est un add-on optionnel sur le pipeline live existant. Vous activez les composants low-latency via les LivePipelineComponents, et le pipeline gère le reste — partial segments, preload hints, server control, tout est coordonné automatiquement.

Un flux live, ça ne sert à rien s'il reste sur votre disque. SegmentPusher envoie les segments vers une ou plusieurs destinations au fur et à mesure de leur production. HTTPPusher fait du HTTP PUT vers n'importe quel endpoint — un CDN, un serveur Nginx, un bucket S3.

Pour les cas plus avancés, l'architecture est ouverte par design. Les protocoles RTMPTransport, SRTTransport, et IcecastTransport sont définis dans HLSKit, mais les implémentations concrètes sont fournies par des libs séparées — swift-rtmp-kit, swift-srt-kit, swift-icecast-kit. C'est de l'injection de dépendances propre : HLSKit reste zéro dépendance, votre app importe les transports dont elle a besoin.

Le MultiDestinationPusher gère les envois en parallèle. Le BandwidthMonitor surveille la bande passante réelle par destination. Si une destination échoue, les autres continuent — pas de point de défaillance unique.

Un flux live sans métadonnées, c'est un tuyau aveugle. HLSKit injecte des métadonnées dans le flux en cours de production — sans interrompre le pipeline.

SCTE-35 pour les coupures pub : SCTE35Marker insère des signaux EXT-X-CUE-OUT / EXT-X-CUE-IN à des moments précis. DATE-RANGE pour les événements temporels — début d'un chapitre, changement de programme, alerte info. ID3 pour les métadonnées timed — titre, artiste, pochette d'album synchronisés avec l'audio. Interstitials pour les coupures HLS — pause pub ou contenu inséré avec EXT-X-ASSET-URI et configuration de resume.

Pendant qu'un flux live est diffusé, SimultaneousRecorder enregistre tout en parallèle — segments et métadonnées — vers un répertoire local. Quand le stream s'arrête, LiveToVODConverter transforme l'enregistrement en playlist VOD standard avec chapitres automatiques.

Le chapitrage est géré par AutoChapterGenerator — les points de coupe SCTE-35 ou les DATE-RANGE deviennent des chapitres dans la version VOD. Votre stream live de 2 heures devient un fichier VOD chapitré en une seule opération.

IFramePlaylistGenerator produit des playlists EXT-X-I-FRAMES-ONLY — des playlists qui ne contiennent que les keyframes, utilisées pour le trick play (avance rapide, retour rapide) et la génération de thumbnails. ThumbnailExtractor extrait les vignettes à intervalle régulier pour les timelines visuelles des lecteurs.

Le module audio offre trois outils indispensables pour les flux broadcast professionnels.

AudioFormatConverter convertit entre formats : MP3 → M4A, WAV → AAC, FLAC → ALAC. LoudnessMeter mesure le loudness intégré en LUFS selon la norme EBU R128 — essentiel pour la conformité broadcast. Et SilenceDetector identifie les plages de silence dans un flux audio, utile pour le chapitrage automatique ou la détection de perte de signal en live.

HLSKit parle le langage des formats professionnels.

Côté audio : Dolby Atmos (via Dolby Digital Plus JOC), AC-3, E-AC-3, multi-canal 5.1 et 7.1.4, audio Hi-Res en 96 ou 192 kHz, 24 ou 32 bits, avec ALAC et FLAC lossless. Les manifestes HLS générés incluent les attributs CHANNELS et les renditions audio alternatives correctement configurées.

Côté vidéo : HDR10, Dolby Vision, HLG, avec le signaling VIDEO-RANGE dans les manifestes. Le support des résolutions va jusqu'au 8K, avec les attributs CODECS qui reflètent précisément les profils encodés. Le tout est transparent pour le pipeline — vous configurez les capabilities dans LivePipelineConfiguration, et les manifestes sont générés avec les bons attributs.

Pour le contenu protégé en live, HLSKit implémente l'intégration FairPlay Streaming avec rotation de clés par segment. Chaque segment peut avoir sa propre clé, et le EncryptionKey permet au lecteur de ne télécharger la clé qu'une seule fois pour une session entière. La combinaison DRM + LL-HLS est supportée — les partial segments héritent de la clé de leur segment parent.

L'accessibilité n'est pas un bonus — c'est une obligation légale pour beaucoup de diffuseurs. HLSKit génère les tags CLOSED-CAPTIONS pour CEA-608 et CEA-708, les pistes de sous-titres WebVTT live, et les renditions audio description. Les manifestes produits sont conformes aux exigences d'accessibilité d'Apple pour la distribution sur l'App Store.

Le parser lit n'importe quel manifeste M3U8 — master playlists, media playlists, et toutes les extensions HLS v7+ y compris Low-Latency HLS. Il retourne un Manifest qui est soit .master(MasterPlaylist), soit .media(MediaPlaylist). Chaque variant, chaque segment, chaque tag est modélisé par un struct Swift typé.

Pour la génération, deux approches. L'API impérative si vous construisez vos playlists dynamiquement :

Et le DSL @resultBuilder si vous préférez une syntaxe déclarative :

Les deux approches produisent du M3U8 conforme à la spec. Le générateur gère le formatage, les tags, les attributs, et tous les détails de sérialisation que la RFC 8216 impose.

Un manifeste peut être syntaxiquement valide mais sémantiquement faux. HLSValidator vérifie les playlists contre deux jeux de règles : la RFC 8216 (le standard IETF) et les règles Apple HLS (plus strictes sur certains points). Chaque violation est classée en erreur, warning ou info.

Le rapport structuré vous dit exactement ce qui ne va pas et pourquoi. Pas de message générique "invalid playlist" — chaque règle a un identifiant, un message, et un niveau de sévérité. Vous savez ce qui bloque avant de déployer, pas après.

C'est le cœur du pipeline HLS : prendre un fichier MP4 et le découper en segments prêts à être servis. HLSKit propose deux formats de sortie — chacun avec ses avantages.

Fragmented MP4 (fMP4) est le format moderne recommandé par Apple. Chaque segment est un fragment MP4 indépendant, précédé d'un segment d'initialisation (init.mp4) qui contient les métadonnées de la piste. C'est le format le plus efficace, celui utilisé par les CDN modernes.

MPEG-TS est le format historique. Chaque segment est autonome et contient ses propres métadonnées — plus lourd, mais compatible avec absolument tous les players, y compris les plus anciens.

Un troisième mode, byte-range, permet de découper un fichier en segments logiques sans le dupliquer physiquement. Les segments sont des plages d'octets dans un seul fichier — utile quand le stockage est contraint.

En live, deux segmenteurs supplémentaires s'occupent du temps réel : AudioSegmenter pour les flux audio purs et VideoSegmenter pour la vidéo. Ils consomment les frames encodées au fil de l'eau et produisent des segments dès que la durée cible est atteinte, sans attendre la fin du flux.

Le segmenteur lit le fichier MP4 au niveau des boxes (les blocs structurels du format ISO BMFF), analyse les sample tables pour trouver les points de découpe optimaux (keyframes), et produit des segments alignés sur les frontières d'échantillons. Pas de glitch audio, pas de frame manquante — la coupe est chirurgicale.

Pour les formats non-ISOBMFF (MP3, WAV, FLAC), HLSKit détecte automatiquement l'incompatibilité et transcode le fichier en M4A avant de segmenter — transparence totale pour l'appelant.

Segmenter un fichier, c'est bien. Mais souvent, vous avez besoin de l'encoder aussi — changer la résolution, le codec, le bitrate. HLSKit propose deux transcodeurs locaux, tous deux conformes au protocole Transcoder.

AppleTranscoder utilise VideoToolbox, le framework bas-niveau d'Apple pour l'encodage matériel. Il exploite les puces dédiées de votre Mac ou iPhone pour encoder en H.264/HEVC beaucoup plus vite qu'en software — et avec une consommation énergétique minimale. Disponible uniquement sur les plateformes Apple.

FFmpegTranscoder wraps le binaire FFmpeg installé sur le système. Cross-platform, compatible Linux, supporte à peu près tous les codecs existants. C'est le choix serveur par défaut.

Les deux implémentent le même protocole Transcoder. Votre code appelant ne change pas — vous pouvez switcher entre Apple et FFmpeg en changeant une seule ligne. Les quality presets (.p360, .p480, .p720, .p1080, .p2160, .audioOnly) sont partagés.

Pour le multi-variante (adaptive bitrate), transcodeVariants() encode vers plusieurs qualités en une seule passe et génère le master playlist automatiquement.

La détection automatique du contenu source (vidéo ou audio seul) ajuste le preset en conséquence — pas de configuration manuelle nécessaire.

Sur un serveur, vous n'avez ni GPU ni FFmpeg. Installer FFmpeg sur une instance cloud minimale, c'est possible, mais pas toujours souhaitable — ça complexifie le déploiement, ça consomme du CPU, et ça ne scale pas.

ManagedTranscoder résout ce problème en déléguant le transcodage à un service cloud. Cloudflare Stream, AWS MediaConvert, ou Mux — vous choisissez le provider, la lib s'occupe de tout : upload du fichier source, création du job, polling du statut, téléchargement du résultat.

Et surtout : ManagedTranscoder implémente le même protocole Transcoder que les transcodeurs locaux. Votre code appelant ne sait pas — et n'a pas besoin de savoir — si le transcodage se fait sur votre machine ou dans un datacenter à 5 000 km.

Un fichier vidéo de 500 Mo, vous ne voulez pas le charger en RAM d'un coup. L'upload et le download streamés envoient et reçoivent les données directement depuis le disque, sans jamais charger le fichier complet en mémoire. Le progress callback rapporte l'avancement de manière granulaire à travers 5 phases : upload (0-30%), création du job (30%), polling (30-80%), download (80-95%), terminé (100%).

Sous le capot, chaque opération de transcodage cloud suit un cycle de vie précis : queued → processing → completed | failed | cancelled. Le ManagedTranscodingJob encapsule cet état avec un jobID, un assetID, le progrès d'encodage, les URLs de sortie quand c'est terminé, et un message d'erreur quand ça ne l'est pas.

Le polling est configurable : intervalle entre les vérifications (pollingInterval, par défaut 5 secondes) et timeout global (timeout, par défaut 1 heure). Par défaut, les assets cloud sont supprimés après le download (cleanupAfterDownload = true) pour éviter les coûts de stockage résiduels.

HLS supporte deux modes de chiffrement pour protéger le contenu — et HLSKit implémente les deux.

AES-128 chiffre chaque segment en entier avec AES-128-CBC. C'est le mode standard, supporté par tous les players. Simple, robuste, avec rotation de clés possible par segment.

SAMPLE-AES est plus fin : il chiffre au niveau des échantillons individuels — les NAL units pour la vidéo H.264, les frames ADTS pour l'audio AAC. Le conteneur reste lisible (headers, métadonnées), seul le contenu média est chiffré. C'est le mode utilisé par les DRM comme FairPlay.

KeyManager génère des clés AES-128 cryptographiquement sûres et dérive les IVs selon la RFC 8216 (numéro de séquence du segment en big-endian sur 16 octets). Il gère aussi la lecture et l'écriture des fichiers de clés — le fichier binaire de 16 octets que le player télécharge pour déchiffrer les segments.

Avant de segmenter ou de transcoder un fichier, il faut savoir ce qu'il contient. MP4BoxReader parse la structure du conteneur ISO BMFF — les fameux "boxes" (ou "atoms" dans le vocabulaire QuickTime) qui organisent un fichier MP4.

MP4InfoParser extrait les informations utiles : pistes audio/vidéo, codecs, résolution, durée, bitrate, timescale. Le tout sans décoder le média — juste la lecture des métadonnées du conteneur.

Plus profondément, SampleTableParser lit les sample tables du conteneur : les tables qui mappent chaque échantillon (frame vidéo, packet audio) à sa position dans le fichier, son timestamp, et sa taille. C'est grâce à ces tables que le segmenteur sait exactement où couper — sur un keyframe, sans casser la timeline.

8 commandes pour les workflows HLS courants, directement depuis le terminal. Pratique pour le scripting, le CI/CD, ou simplement pour tester rapidement sans écrire de code.

La lib est découpée en modules fonctionnels, chacun responsable d'une étape du pipeline. Zéro dépendance externe dans le core HLSKit — seul le CLI utilise swift-argument-parser pour le parsing des arguments.

Chaque module peut être utilisé indépendamment. Vous n'avez besoin que du parser ? Importez HLSKit et utilisez ManifestParser. Besoin de segmenter sans transcoder ? MP4Segmenter est autonome. Besoin d'un pipeline live audio ? Assemblez AudioEncoder + AudioSegmenter + SlidingWindowPlaylist + HTTPPusher dans un LivePipeline. Le tout est relié par deux façades : HLSEngine pour le VOD, et LivePipeline pour le temps réel.

4 478 tests répartis dans 526 suites — modèles, parser, générateur, validateur, segmenteur, transcodeur, chiffrement, conteneur, transport, engine, encodeur, segmenteur live, playlist live, LL-HLS, push, métadonnées, enregistrement, I-Frame, audio, spatial audio, HDR, DRM, accessibilité, résilience, pipeline, CLI. Zéro XCTest — 100% Swift Testing (import Testing).

Les showcase tests servent de documentation exécutable : chaque API publique a au moins un test qui montre comment l'utiliser. Les exemples de code dans le DocC et dans cet article sont tirés de ces tests — ce qui est écrit ici a été compilé et exécuté.

La documentation complète est disponible en DocC, intégrée au package. 26 guides couvrent chaque étape du pipeline — VOD et live — avec des exemples exécutables.

Les spécifications et standards sur lesquels s'appuie HLSKit — 31 au total :