Démo de flux vidéo de drone
Un flux vidéo MPEG-2 TS synthétique, avec une télémétrie KLV MISB ST 0601/0102 réelle, envoyé un segment HLS à la fois vers une source de données média video/mp2t, indexé pour la route de playlist M3U8.
La source de données d'exemple drone-video-stream-v1 (apps/docs/examples/drone-video/manifest.ts) est une sœur de drone-camera : cet exemple envoie des images fixes et des clips enregistrés entiers ; celui-ci envoie un flux vidéo en HLS sur HTTP, un segment MPEG-2 TS à la fois, chacun portant une télémétrie KLV MISB ST 0601 réelle. Chaque octet est synthétique et construit en mémoire par le script d'envoi (uploader/push.ts) — jamais un fichier d'exemple tiers de licence inconnue, et aucun capteur ou drone réel n'est impliqué.
Ce qui est envoyé, et ce qui atterrit dans la table
Chaque envoi est un segment TS (video/mp2t) plus une partie de métadonnées JSON nommant le stream, la sequence, le start, le end et la duration du segment — le même champ segment que le runtime d'envoi lit indépendamment de toute correspondance de ligne (parseSegmentMetadata). Les octets du segment lui-même sont indexés dans data_source_media_segment dès que l'élément lui-même est enregistré, et chaque paquet KLV décodé du segment s'engage comme sa propre ligne, sous le vocabulaire de ligne KLV fixe du runtime d'ingestion — capturedAt, sensorLat/sensorLon/sensorAltM, platformHeadingDeg, sensorAzimuthDeg/sensorElevationDeg/sensorRollDeg, frameCenterLat/frameCenterLon/frameCenterElevationM, footprint, unknownTags — plus mediaRef, la colonne que chaque ligne porte en référence à son propre segment. La table déclare exactement ces colonnes, en camelCase, car ces lignes contournent entièrement ingest.mapping : il est vide ici, puisque cette source n'écrit aucune ligne d'une autre façon.
Un paquet peut porter des tags MISB que ce décodeur ne mappe à aucun nom ; plutôt que de les deviner ou de les abandonner silencieusement, chaque tag non mappé est conservé tel quel dans unknownTags, un tableau JSON de {tag, data} par ligne, data encodé en base64 — la même convention de passage d'octets en JSON déjà utilisée pour les messages mis de côté d'un flux. unknownTags est absent (jamais un tableau vide) sur une ligne dont le paquet ne portait aucun tag non mappé.
Le générateur propre du script d'envoi (klvPacketBytes, issu du point d'entrée testing de @scrydon/common, afin que cet exemple réutilise exactement le même fixture dont les tests propres du runtime d'ingestion prouvent déjà le décodage correct) n'exerce que l'horodatage d'un paquet et, optionnellement, son indicateur de sécurité ST 0102 — les indicateurs de capteur/position/angle/centre d'image d'un paquet décodé relèvent de la surface déjà prouvée de decodeKlvPacket, non re-prouvée ici, donc chaque ligne que cette démo écrit a ces colonnes à null. Chaque colonne sauf mediaRef et la clé primaire (capturedAt) est nullable pour exactement cette raison, de la même façon qu'une trame de battement de cœur dans drone-camera écrit une ligne de détection avec chaque champ spécifique à la détection à null plutôt que zéro ligne.
La correspondance d'étiquette ST 0102 → plateforme
L'ensemble de sécurité ST 0102 décodé d'un segment TS peut porter une revendication de classification qui ne peut jamais que relever l'étiquette sous laquelle le segment (et toute ligne KLV admise) s'engage — jamais l'abaisser, et jamais sous l'étiquette propre configurée de la source. L'énumération à cinq niveaux de ST 0102 se projette sur l'échelle à quatre niveaux propre de la plateforme :
| Classification ST 0102 | Étiquette de la plateforme |
|---|---|
unclassified | public |
restricted | confidential |
confidential | confidential |
secret | restricted |
top_secret | restricted |
restricted plafonne à confidential, et non à internal : chaque niveau KLV classifié atterrit à confidential ou plus haut, afin qu'une revendication ne soit jamais prise pour une revendication non classifiée — relèvement uniquement, et la correspondance penche vers l'étiquette la plus haute chaque fois qu'un niveau n'a pas d'équivalent exact côté plateforme (secret et top_secret plafonnent tous deux à restricted, le plafond propre de la plateforme, puisqu'il n'y a aucun niveau au-dessus pour les distinguer).
Un ensemble de sécurité qu'un paquet affirme n'est jamais lu comme une absence de revendication, même lorsque son propre octet de classification ne peut être mappé (absent, trop court, ou non reconnu) : cela relève vers restricted, le même plafond, en échouant fermé plutôt qu'en étant silencieusement laissé passer — comptabilisé (KLV_WITHHELD_REASON.SECURITY_UNRECOGNIZED) chaque fois, que ce relèvement retienne ou non des lignes au final.
Pourquoi une revendication relevée peut retenir des lignes KLV, jamais la vidéo
Lorsque la revendication d'un segment relèverait son étiquette au-dessus de l'étiquette propre configurée de la source installée, la réponse de la Plateforme à l'enregistrement du segment retient uniquement les lignes KLV de ce segment hors de la table — jamais les octets du segment, qui restent conservés (et servis, et joués) à l'étiquette relevée quoi qu'il arrive. Une table ne porte qu'une seule étiquette pour chacune de ses lignes ; une ligne dont le propre segment revendique une étiquette plus haute que celle de la table ne peut y atterrir sans sous-étiqueter celle-ci, elle est donc comptée (KLV_WITHHELD_REASON.LABEL_RAISED) et laissée de côté, tandis que la vidéo elle-même reste exactement aussi disponible que tout autre segment, à sa nouvelle étiquette relevée.
L'échantillonnage à 1000 lignes et le compteur de paquets défectueux
Les paquets KLV décodés d'un segment ne sont jamais écartés depuis le DÉBUT lorsqu'ils sont plus nombreux que la place disponible dans le lot d'engagement (SOURCE_BATCH_LIMITS.MAX_ROWS, 1000) : ils sont échantillonnés uniformément sur l'ensemble du segment, la première ligne étant conservée, afin qu'une piste jointe au segment voie toujours toute son étendue, à un rythme plus faible, plutôt que seulement ses premières secondes. Le reste est compté (KLV_WITHHELD_REASON.BATCH_LIMIT), jamais silencieusement écarté. Un paquet qui échoue son propre contrôle CRC-16 est mis en quarantaine de la même façon — compté (KLV_WITHHELD_REASON.PACKET_UNREADABLE) et ignoré — tandis que le reste des paquets du segment, et le segment lui-même, ne sont pas affectés : un paquet défectueux coûte une ligne, jamais le clip.
La lecture
Une fois drone-video-stream-v1 installée et après que le script d'envoi a poussé quelques segments pour un flux (cam-1, cam-2, …), la fenêtre du flux est servie comme une playlist média HLS :
- La route de playlist M3U8 —
GET /api/data-sources/media-segments/:sourceId/:streamId/playlist.m3u8?from=…&to=…(une fenêtre de deux heures au plus) construit une playlist média HLS standard à partir des segments que le lecteur connecté peut voir. L'URI de chaque segment est la route de lecture gouvernée par élément, de sorte que les octets de chaque segment sont vérifiés contre l'habilitation du lecteur et audités lorsqu'un lecteur vidéo les récupère. Les segments laissés de côté pour ce lecteur sont seulement comptés, dans l'en-tête de réponsex-media-hidden, jamais décrits. Segments TS uniquement en v1 (une fenêtre fMP4 répond409 segment_format_not_playable— pas encore de segment d'initialisation pour en jouer un). - Le lecteur hls.js — le panneau Média récent d'une source affiche un lecteur pour chaque flux auquel appartiennent ses segments TS récents (la build
hls.jsvendue et épinglée par SRI partout où le navigateur dispose des Media Source Extensions, et le HLS natif seulement là où il n'en a pas, comme sur iOS Safari). Chaque lecteur s'ouvre sur les dix minutes qui précèdent le segment listé le plus récent de ce flux, si bien qu'un flux arrêté plus tôt joue encore ses dernières minutes. Les images et les clips enregistrés restent des vignettes.
Les segments synthétiques du script d'envoi ne portent que le flux de métadonnées KLV, sans image : la playlist et chaque lecture de segment fonctionnent de bout en bout, mais un lecteur vidéo n'en tire aucune piste vidéo à afficher.
L'exécuter
bun test --isolate apps/docs/examples/drone-video/manifest.test.ts
bun test --isolate apps/docs/examples/drone-video/uploader/push.test.ts# Aucun réseau du tout -- affiche les métadonnées et le nombre d'octets de chaque segment.
cd apps/docs/examples/drone-video/uploader
bun run push.ts --dry-run --segments 2
# Contre une source réellement installée :
DRONE_VIDEO_PUSH_SECRET=<le secret d'envoi de la source> \
bun run push.ts --endpoint <url-de-la-source-push> --segments 5Le test du manifeste valide la source push (la liaison média video/mp2t, le calibrage du débit d'éléments, les noms de colonnes exacts du vocabulaire de ligne KLV, la correspondance vide). Le test du script d'envoi vérifie que la livraison signée passe le contrôle HMAC propre du runtime d'envoi, sur le corps multipart exact qu'il envoie, que deux flux ne partagent jamais un capturedAt (la clé primaire propre de la table en dépend), que les numéros de séquence ne laissent jamais d'écart au sein d'une même exécution du script d'envoi, et que les segments d'une exécution se terminent à l'horloge propre de cette exécution (un numéro de séquence est le créneau de 6 s du segment depuis l'époque Unix, de sorte qu'une seconde exécution prolonge les mêmes flux).
En direct depuis un drone DJI (écran du téléphone + RTMP)
Un DJI Neo n'a pas de liaison descendante directe que cette démo puisse parler, donc le moyen le plus simple d'obtenir de la vraie vidéo de drone est le téléphone du pilote lui-même : enregistrer l'écran de l'application DJI Fly et rediffuser cet enregistrement en RTMP, uniquement sur le Wi-Fi local, vers un petit relais (relay/) qui le transforme en exactement les mêmes envois de segments HTTPS signés que uploader/push.ts envoie déjà. Rien ici n'est une seconde voie d'ingestion — c'est le même contrat d'envoi, alimenté par un vrai enregistrement plutôt que par le générateur synthétique.
Ce qui tourne où :
- Téléphone : n'importe quelle application de streaming compatible RTMP, pointée vers l'adresse LAN de ce Mac — enregistrement d'écran (ou mise en miroir) de la vue de vol propre de DJI Fly. Masquer la superposition de télémétrie/commandes à l'écran de DJI Fly dans ses propres réglages lorsque l'application le permet ; le relais la recadre également (voir ci-dessous) en seconde protection.
- Mac/boîtier de site : MediaMTX (sous licence MIT ;
brew install mediamtx, conçu ici pourv1.21.2) reçoit le flux RTMP, recadre la superposition de DJI Fly avecffmpeg, enregistre le flux recadré en segments MPEG-2 TS de 6 s, et envoie chaque segment terminé via le mode--filedeuploader/push.ts— la même livraison multipart signée HMAC que tout autre appelant de push.ts. - Échantillonnage Sauron :
relay/stream_frame_source.pysaisit une image JPEG toutes les--interval-secondsdepuis la sortie RTSP propre du relais (rtsp://127.0.0.1:8554/neo_cleanpar défaut) pour la voie de détection du script d'envoi drone-camera. Ce branchement (une source de capture--stream-urlaux côtés de--watch-folder/--screen-region/--camera) doit vivre dansupload.pydedrone-camera, qui se trouve sur une autre branche que ce relais —stream_frame_source.pyest écrit de façon autonome, avec exactement le même contratcapture() -> bytes, afin de s'y brancher sans seconde voie d'envoi de détection une fois cette autre branche et celle-ci réunies.
Le RTMP ne quitte jamais le réseau local (issue #5842) : l'écouteur RTMP de MediaMTX se lie exactement à l'IP LAN détectée de cette machine (jamais un 0.0.0.0/:1935 nu, qui répondrait aussi sur une interface VPN/publique que cette machine pourrait avoir) pour qu'un téléphone sur le même Wi-Fi puisse l'atteindre — rien ici n'ouvre de port entrant vers internet, et la seule chose que le relais envoie hors de la machine est l'envoi de segment HTTPS signé, exactement comme le script d'envoi synthétique.
Un seul identifiant peut y publier. L'authentification de publication propre à MediaMTX (authInternalUsers) est activée : start.sh génère un identifiant aléatoire à chaque exécution et l'affiche une seule fois, à côté de l'URL rtmp:// — la même logique « remis à l'opérateur une fois, jamais stocké » que la clé de session de la page de capture du téléphone. L'application de streaming du téléphone doit fournir cet identifiant en paramètres de requête de l'URL RTMP (?user=…&pass=… — la forme propre à MediaMTX pour cela, pas une URL user:pass@host) pour publier ; tout autre flux atteignant le port RTMP lié est refusé. Les lectures (les deux chemins RTSP — le flux brut que l'étape de republication relit, et le flux propre échantillonné par Sauron) ne sont permises que depuis 127.0.0.1/::1, jamais hors de cette machine — vérifié contre le vrai binaire mediamtx v1.21.2 (voir Ce que cela ne prouve pas ci-dessous pour ce que cette vérification a couvert, ou non).
Chaque autre écouteur MediaMTX que ce relais n'utilise jamais est désactivé. Les réglages par défaut de MediaMTX démarrent aussi un serveur HLS, un serveur WebRTC, des écouteurs SRT et MoQ, et des ports UDP RTP/RTCP — chacun lié à toutes les interfaces de cette machine, pas seulement à la liaison RTMP limitée au LAN ci-dessus, si bien qu'une publication authentifiée sur l'un d'eux pourrait atteindre ce relais depuis hors du Wi-Fi, et qu'une publication non authentifiée pourrait quand même entrer en collision avec un port déjà utilisé. La configuration générée les désactive tous (hls: false, webrtc: false, srt: false, moq: false, rtspTransports: [tcp]) — ce relais ne parle que RTMP en entrée et RTSP/TCP en sortie, rien d'autre.
Exécuter le relais :
bun test --isolate apps/docs/examples/drone-video/relay/config.test.ts
bun test --isolate apps/docs/examples/drone-video/relay/render-config.test.ts
bun test --isolate apps/docs/examples/drone-video/relay/backlog.test.ts
bun test --isolate apps/docs/examples/drone-video/relay/loss-counters.test.ts
python3 -m pytest apps/docs/examples/drone-video/relay/stream_frame_source_test.pyRELAY_PUSH_ENDPOINT=<url-de-la-source-push> \
DRONE_VIDEO_PUSH_SECRET=<le secret d'envoi de la source> \
apps/docs/examples/drone-video/relay/start.shstart.sh vérifie la présence de mediamtx/ffmpeg/bun/openssl sur PATH, génère l'identifiant de publication RTMP de la session (RELAY_RTMP_PUBLISH_USER/RELAY_RTMP_PUBLISH_PASS, créé à moins que l'opérateur n'ait fixé le sien), génère la configuration MediaMTX (relay/config.ts), affiche l'URL exacte rtmp://<IP-LAN-de-ce-Mac>:1935/neo et cet identifiant à saisir dans l'application du téléphone, puis remplace son propre processus par mediamtx (exec) — un Ctrl-C ou un kill sur ce processus va directement à MediaMTX, qui possède et récupère son propre enfant ffmpeg lancé via runOnReady, si bien que l'arrêter ne laisse jamais de processus orphelin.
Chaque réglage est modifiable via des variables d'environnement lues par relay/render-config.ts (marges de recadrage — RELAY_CROP_TOP_PX/RELAY_CROP_BOTTOM_PX/RELAY_CROP_LEFT_PX/RELAY_CROP_RIGHT_PX, par défaut 120/160/0/0, une valeur de démonstration pour DJI Fly et non une mesure d'un téléphone ou d'une orientation précis — ports, noms des chemins RTMP/propre, identifiant de flux, longueur de segment, tentatives d'envoi, et le plafond de backlog ci-dessous) ; voir RelayOptions dans relay/config.ts pour la liste complète.
Un backlog borné, jamais illimité. Chaque segment terminé reste sur le disque jusqu'à ce que son propre envoi réussisse (la nouvelle tentative/temporisation déjà existante de uploader/push.ts, désormais avec une temporisation de 10 s par tentative pour qu'une requête bloquée ne puisse pas bloquer indéfiniment) ; rien ne plafonnait auparavant le nombre de segments conservés pouvant s'accumuler pendant une interruption d'envoi prolongée. push.ts applique désormais un plafond sur son propre répertoire d'enregistrement avant chaque envoi — RELAY_MAX_BACKLOG_FILES (par défaut 50, cinq minutes à la cadence de 6 s) et RELAY_MAX_BACKLOG_BYTES (par défaut 200 Mio) — en évinçant d'abord les segments conservés les plus anciens, jamais celui en cours d'envoi ni ses propres fichiers de comptabilité (le fichier de compteurs, un marqueur .failed-attempt). Un segment conservé n'est pas seulement évincé : l'envoi de chaque nouveau segment vide (republie) aussi le seul plus ancien AUTRE segment conservé en premier, afin qu'une interruption transitoire se rétablisse d'elle-même sans intervention de l'opérateur. Chaque éviction et chaque envoi qui épuise ses tentatives est comptabilisé dans un petit fichier de compteurs par répertoire (.relay-loss-counters.json) et journalisé bruyamment sur stderr — chaque segment compté exactement une fois, qu'il soit finalement récupéré, évincé, ou les deux tenté et perdu, jamais deux fois pour le même segment.
Ce que ce plafond de backlog ne fait pas encore : les compteurs de perte en cours sont locaux au propre répertoire du relais — ils apparaissent dans ses propres journaux, pas (encore) dans les signaux de santé de la source installée dans Analytics. Les y faire apparaître signifierait un compteur au niveau de la source, et non par flux (le mécanisme existant windowFacts/dataSourceSignals que cette revue a examiné n'a aucune dimension par flux, et repose sur une connexion détentrice d'un bail qu'un envoi de segment ponctuel n'a jamais) — laissé pour une conception de suivi, jamais fait à moitié silencieusement.
Latence et limites : la latence de bout en bout correspond grossièrement à la longueur du segment (6 s) plus le temps qu'ajoutent l'envoi et la mise en mémoire tampon propre de MediaMTX — des secondes, pas la latence sous la seconde d'une ingestion directe vers la plateforme ; il s'agit d'un téléphone enregistrant l'écran de prévisualisation vidéo propre d'une application de contrôleur, réencodé deux fois (le rendu propre de DJI Fly, puis le recadrage/transcodage du relais), donc il faut s'attendre à une perte de qualité et des artefacts de compression visibles par rapport à la liaison descendante native du drone. Le recadrage de la superposition est une marge de pixels fixe, pas consciente de la superposition elle-même : un changement de mise en page de DJI Fly, un rapport d'aspect de téléphone différent, ou une rotation du téléphone peuvent remettre l'affichage tête haute dans le cadre et nécessitent un ajustement des marges de recadrage.
Ce que cela prouve, en direct : la configuration générée, exécutée contre le vrai binaire mediamtx v1.21.2 sur des ports alternatifs en loopback uniquement — une publication authentifiée (ffmpeg, en RTMP) est acceptée et un segment est enregistré via l'étape de republication/recadrage ; une publication sans identifiant, et une avec le mauvais mot de passe, sont toutes deux refusées ; seuls les deux écouteurs que ce relais utilise (RTMP, RTSP) ouvrent jamais un port.
Ce que cela ne prouve toujours pas : aucun flux RTMP réel depuis un vrai téléphone, aucun enregistrement d'écran DJI Fly, et start.sh lui-même n'ont été exercés (la vérification ci-dessus a exécuté directement la configuration générée, pas le script) ; les calculs de recadrage, le comportement d'envoi/nouvelle tentative/vidange/backlog par segment, et l'échantillonneur d'images restent testés unitairement contre des simulacres (pas de vrai ffmpeg pour ceux-ci, pas de vraie source RTSP) ; qu'une publication authentifiée sur un protocole que ce relais désactive (SRT/WebRTC/MoQ) puisse atteindre le relais depuis hors du LAN a été raisonné (ces écouteurs ne démarrent jamais du tout) mais pas lui-même tenté.
Ce que cette démo ne prouve pas : une liaison vidéo descendante réelle de drone ni un encodeur KLV MISB réel, un lecteur affichant de la vidéo (les segments synthétiques ne portent aucune image), ni les débits et volumes d'ingestion en production.