Médias : commandes CLI

Convertir un fichier local en octets de livraison, le téléverser et attendre que l’objet soit prêt.

media upload <file> [--content-type TYPE] [--tag TAG] [--folder ID] [--no-wait] [--poll-ms MS]
             [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
             [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
             [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoop

La vidéo devient un MP4 : profil High H.264 au niveau 4.2, 5.1 ou 5.2, le plus bas adapté à la taille et à la cadence, ou profil Main H.265 au niveau 5.1 ou 5.2 avec --codec hevc, en yuv420p balisé Rec. 709, d’au plus 3840 par 2160 pixels par image. Une source HDR est mappée en tonalité vers Rec. 709. L’audio, lorsque la source en a, est AAC à 192 kbit/s, 48 kHz, stéréo.

Les images fixes deviennent WebP avec perte à la qualité 90, conservant l’alpha si la source en a. Une source animée boucle indéfiniment. Un WebP déjà conforme à la limite de taille est transmis sans réencodage.

L’audio devient un MP3 pour une bande sonore de liste de lecture. Une source MP3 se téléverse inchangée ; les sources WAV, AAC, M4A, OGG et FLAC sont converties en MP3 128 kb/s, ce qui nécessite une build ffmpeg avec libmp3lame. Une piste dure de 1 seconde à 3 heures. playlist init transforme les entrées audio en pistes de bande sonore plutôt qu’en pages. L’objet prêt est un objet média audio avec une durée. Il ne peut pas être placé sur une page ; nommez-le dans la liste de lecture audio bande sonore à la place.

L’identifiant de l’objet prêt est data.media_id. La même valeur est data.id et data.operation.result.media_id. Cet identifiant est ce qu’un sélecteur de liste de lecture prend.

Un média prêt avec les mêmes octets, le même nom de fichier et la même étiquette est renvoyé au lieu d’être téléversé à nouveau (data.reused vaut true), de sorte que relancer un téléversement interrompu renvoie son ID de média. data.timing indique les millisecondes par étape : prepare_ms (conversion et empreinte), declare_ms, transfer_ms, commit_ms et processing_ms (jusqu’à l’état prêt, aussi fin que --poll-ms ; absent avec --no-wait).

Un nom de fichier peu informatif tel que video.mp4 ajoute un avertissement consultatif generic_filename à l’enveloppe. Le téléversement réussit quand même et la CLI ne renomme jamais le fichier ; choisissez le nom avant d’exécuter la commande.

Les conversions exécutent ffmpeg et ffprobe depuis PATH, ou depuis les chemins absolus dans SCREENRIG_FFMPEG et SCREENRIG_FFPROBE. Les images fixes préfèrent l’encodeur ffmpeg libwebp et retombent sur cwebp sur PATH ou SCREENRIG_CWEBP. Exécutez doctor avant le premier téléversement d’une session.

--preset signage-1080p30 limite le grand côté à 1920, le petit côté à 1080, et le taux à 30 ips constant. signage-4k30 limite le grand côté à 3840, le petit côté à 2160, et le taux à 30 ips constant. Les deux fonctionnent avec du contenu paysage, portrait et carré. --no-audio omet l’encodage audio pour les clips silencieux. Ces options s’appliquent uniquement à la vidéo.

screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audio

screenrig media upload ./menu.png --folder mfd_01EXAMPLEFOLDER000000000

media upload-batch --folder place de la même façon chaque élément téléversé dans le dossier.

Une image ou une vidéo peut mesurer jusqu’à 16383 pixels en largeur ou en hauteur et 67 108 864 pixels (8192 par 8192) dans une image ; une image plus grande est refusée avec invalid_request. La conversion par défaut ajuste chaque côté à 3840 pixels, donc téléversez un master ultra-large comme 9216 par 2160 ou 12000 par 540 avec --no-transcode. Un téléversement vidéo peut atteindre au plus la plus grande vidéo autorisée par le plan du projet, que project capabilities rapporte sous le nom media_video_bytes (voir Tarification) ; une vidéo plus grande est refusée avant d’être lue, donc raccourcissez d’abord le clip. La CLI encode la vidéo à une qualité fixe, donc une longue vidéo peut encore dépasser la limite après l’encodage et est alors refusée ; avec --no-transcode, le fichier lui-même doit respecter la limite.

Un transfert vers le stockage interrompu est tenté jusqu’à 4 fois tant que son URL de téléversement est valide. S’il échoue encore, l’erreur nomme l’operation_id du téléversement et le téléversement est annulé pour ne retenir aucun stockage ; avec --idempotency-key, il est conservé pour la reprise. Relancez la même commande.

Avec un accès Proposer, ou lorsque le projet exige une révision pour les modifications d’agent, un nouveau téléversement attend la révision d’une personne avant qu’une étiquette, un dossier ou un sélecteur all ne le diffuse ; voir Révisions.

Téléversez plusieurs fichiers locaux à partir d’un manifeste, en reprenant depuis un fichier d’état.

media upload-batch <manifest.json> [--state FILE] [--concurrency N] [--tag TAG] [--folder ID]
                   [--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc]
                   [--max-fps N] [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
                   [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media upload-batch ./images.json --state ./upload-state.json

L’enveloppe transporte data.items[] dans l’ordre du manifeste, chacun avec path, source_filename, sha256, outcome (accepted ou resumed), et media_id. data.failed[] transporte les éléments qui n’ont pas abouti, chacun avec son path et son problem ; data.accepted, data.resumed, data.attempts, data.rate_limited, data.wait_ms et data.transfer_ms comptabilisent l’exécution. Un élément est tenté jusqu’à 8 fois, avec une attente entre les essais, tant que la réponse est une limite de débit ou une erreur de serveur.

En cas d’échecs, le code de sortie suit le dernier élément en échec : 7 pour une limite de débit, 9 pour une erreur de serveur, 2 pour une erreur d’usage, sinon 8. Relancez la même commande avec le même manifeste pour ne téléverser que ce qui n’a pas abouti.

Remplacer le fichier d’un média sur place. Son id, ses playlists et ses programmations continuent de fonctionner.

media replace <id> <file> [--expect-rev REVISION] [--note TEXT] [--content-type TYPE] [--no-wait]
              [--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
              [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
              [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media replace med_01EXAMPLEIMAGE0000000000 ./menu-v2.png
screenrig media replace med_01EXAMPLEVIDEO0000000000 ./intro.mp4 --expect-rev 3 --note "Spring cut"

Le média garde son ID, ses étiquettes et son dossier, de sorte que chaque liste de lecture et chaque programmation qui le nomment jouent le nouveau fichier au prochain manifeste, et que les sélecteurs par étiquette, dossier et all le reprennent aussi. Rien n’est reprogrammé. La commande exécute les mêmes étapes que media upload (conversion, la limite d’octets vidéo du forfait, les limites de dimensions, la limite de stockage du forfait, le transfert signé), puis remplace au lieu d’ajouter un nouveau média. Elle n’accepte ni --tag ni --folder.

Par défaut la commande attend la fin du traitement. data.media_id et data.id sont l’id du média, data.version est le numéro du nouveau fichier dans media versions, et data.revision est la nouvelle révision du média. data.warnings, data.operation, data.upload, data.transcode et la durée sont rapportés comme pour media upload, et l’id d’opération figure sur l’enveloppe. Avec --no-wait, data.operation est l’opération acceptée, et data.version et data.warnings sont absents.

Un changement de rapport d’aspect est permis. L’enveloppe porte un avertissement aspect_ratio_changed, et data.warnings[].playlists nomme les playlists qui utilisent le média ; vérifiez donc leur rendu. Un fichier aux mêmes octets que l’actuel est refusé avec resource_conflict (code de sortie 13).

Chaque fichier antérieur reste dans l’historique du média et compte dans les octets stockés jusqu’à la suppression de sa version ; voir media versions.

Avec l’accès Propose, ou quand le projet exige une révision pour les modifications d’agent, le remplacement attend une personne et la commande réussit (code de sortie 0) : data.status est pending_review, data.review_id nomme la révision, l’avertissement pending_review donne son URL et data.next est screenrig reviews show ID. Le média continue de jouer son fichier actuel jusqu’à l’approbation d’une personne ; dites-lui donc qu’il attend et ne répétez pas l’écriture. Un remplacement plus récent du même média remplace celui qui attend. Voir Révisions.

Lister les fichiers qu’a eus un média, le fichier en service en premier.

media versions <id> [--limit N] [--cursor CURSOR]

screenrig media versions med_01EXAMPLEIMAGE0000000000

data.items contient une entrée par fichier qu’a eu le média : number, current, filename, source_filename, content_type, sha256, bytes, width, height, duration_ms, codecs, source (upload, replace, sync ou restore), note, by (type person, agent, client ou sync, avec identifiant et nom), restored_from et created_at. Le fichier en service vient en premier (current: true), puis les autres du plus récent au plus ancien. La version 1 est le premier téléversement ; chaque remplacement, restauration ou changement de synchronisation de médias ajoute le numéro suivant.

Sans --limit ni --cursor, toutes les pages sont lues et data.next_cursor vaut null. Avec l’un des deux, une seule page est lue : tant que data.next_cursor est une chaîne, relancez la commande avec --cursor défini sur cette valeur. L’accès Lecture seule suffit. Les octets d’une version passée restent stockés et comptent dans les octets stockés du projet jusqu’à ce que media version delete les supprime ; le nombre de versions conservées n’est pas limité, et les octets stockés au-delà du stockage gratuit du plan sont facturés comme tout autre stockage.

Remettre une version passée en service comme nouvelle version.

media restore <id> --number N [--expect-rev REVISION] [--note TEXT]

screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2 --expect-rev 5 --note "Back to the winter menu"

Le média garde son id et passe à une nouvelle révision, et chaque playlist et chaque programmation qui le nomme rejoue ce fichier. La version qu’elle copie reste dans l’historique et partage ses octets ; la nouvelle version compte dans les octets stockés comme n’importe quelle autre. data.media est le média et data.warnings porte aspect_ratio_changed, qui nomme les playlists utilisant le média, quand le fichier restauré a un autre rapport d’aspect.

La version en service ne peut pas être restaurée (resource_conflict, code de sortie 5), et une version inconnue est not_found (code de sortie 4). Avec l’accès Propose, ou quand le projet exige une révision pour les modifications d’agent, la restauration attend une personne et la commande réussit (code de sortie 0) : data.status est pending_review avec data.review, l’avertissement pending_review donne son URL et data.next est screenrig reviews show ID. Le média continue de jouer son fichier actuel jusqu’à l’approbation d’une personne ; ne répétez donc pas l’écriture.

Supprimer une version passée et ses octets stockés.

media version delete <id> --number N

screenrig media version delete med_01EXAMPLEIMAGE0000000000 --number 2

L’enregistrement de la version disparaît et ses octets quittent aussitôt les octets stockés du projet. L’objet stocké est retiré au bout de 24 heures, sauf si une autre version ou le fichier en service détient le même fichier. Une version supprimée ne peut pas être restaurée. La version en service ne peut pas être supprimée, et aucune version ne peut l’être tant qu’un remplacement du média attend une révision ; les deux cas sont resource_conflict (code de sortie 5), et media versions ID montre quelle version est en service. Une version inconnue est not_found (code de sortie 4). La suppression exige l’accès Manage : un identifiant Propose est refusé avec insufficient_access, et la suppression n’est jamais proposée à révision.

Lire un objet média, y compris sa révision actuelle.

media show <id>

screenrig media show med_01EXAMPLEIMAGE0000000000

Écrivez une version stockée sur disque pour inspection. N’imprimez jamais les octets.

media download <id> [--output FILE]

screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webp

La réponse indique media_id, path, bytes, sha256, content_type, primitive, filename, source_filename facultatif et width / height. Elle ne contient jamais de pixels. Utilisez-la pour vérifier une image avant qu’elle passe à l’écran.

Lister les objets médias, filtrés optionnellement par étiquette, type primitif et dossier.

media list [--tag TAG] [--primitive image|video|audio] [--folder ID|root] [--library]

screenrig media list --tag LobbyLoop --primitive video
screenrig media list --folder mfd_01EXAMPLEFOLDER000000000
screenrig media list --library

Chaque ligne comporte folder_id, qui est absent à la racine de la bibliothèque.

Prévisualiser quels fichiers prêts un sélecteur de médias dynamique retient maintenant, sans publier de liste de lecture ni faire avancer un Player.

media selector-preview <selector.json> --primitive image|video [--rect WxH] [--timezone IANA]

screenrig media selector-preview selector.json --primitive video
screenrig media selector-preview selector.json --primitive image --timezone America/New_York

Les clés du sélecteur (order, batch_size, one_at_a_time, weights et fit) sont décrites sous Filtres d’étiquettes et lots de lecture et Rotation pondérée et ajustement au format.

La réponse contient matched_count, les candidates classés par nom de fichier (media_id, filename, tags, width, height), le selector normalisé et, dans excluded, les fichiers écartés avec leur reason : aspect_mismatch pour fit: "aspect", et outside_window pour un fichier dont la règle de disponibilité ne tient pas maintenant. Avec order: "weighted", chaque candidat porte weight et share_percent, et cycle est le nombre de lectures après lequel chaque élément a joué exactement son poids. Plus de 1024 correspondances donne invalid_request. L’accès en lecture suffit. La prévisualisation lit le projet authentifié, ne fait jamais avancer un curseur ni ne modifie un manifeste, et un changement du catalogue après elle est pris en compte à la prochaine limite de boucle de chaque Player.

Remplacer ou effacer les étiquettes d’un objet. Sa règle de disponibilité se définit avec media availability.

media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]

screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop
screenrig media update med_01EXAMPLEIMAGE0000000000 --tags Summer,Drinks

Avec un accès Proposer, ou lorsque le projet exige une révision pour les modifications d’agent, le retagging des médias approuvés répond à ok avec l’avertissement media_review_pending : les écrans continuent de le diffuser avec ses étiquettes approuvées jusqu’à ce qu’une personne approuve le changement, et un rejet remet les étiquettes en place. Sa révision apparaît dans reviews list en quelques secondes ; un retag qui ne change aucune playlist approuvée ni playlist en attente de révision s’applique seul. Voir Révisions.

Définit ou efface le moment où les sélecteurs dynamiques peuvent choisir un fichier.

media availability <id> (--file FILE | --clear) [--expect-rev REVISION]

screenrig media availability med_01EXAMPLEIMAGE0000000000 --file rule.json

Les membres et le comportement de la règle figurent sous Disponibilité des médias. Un fichier en attente de révision par une personne est refusé avec media_pending_review : décidez d’abord de sa révision.

Supprimer un objet média.

media delete <id> [--expect-rev REVISION]

screenrig media delete med_01EXAMPLEIMAGE0000000000

Déplacez les fichiers médias et les dossiers dans un dossier, ou retour à la racine de la bibliothèque.

media move <id>... (--folder ID | --root)

screenrig media move med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --folder mfd_01EXAMPLEFOLDER000000000
screenrig media move mfd_01EXAMPLEFOLDER000000000 --root

Le déplacement est une requête tout ou rien. Un dossier ne peut pas se déplacer dans lui-même ni dans un dossier qu’il contient, et les dossiers s’imbriquent au maximum sur 10 niveaux. Les éléments déjà dans la destination restent tels quels. data.media et data.folders comptent ce qui a été déplacé.

Le déplacement de fichiers modifie ce que les sélecteurs by:folder de leurs anciens et nouveaux dossiers jouent, à partir de la résolution du sélecteur suivant de chaque écran ; déplacer un dossier ne change pas les fichiers propres à un dossier. Sous Propose access, ou lorsque le projet exige une révision pour les modifications d’agent, chaque fichier déplacé attend la révision d’une personne (reviews list) et les listes de lecture approuvées continuent de le jouer par le dossier avec lequel il a été approuvé ; voir Révisions.

Lister les dossiers médias du projet.

media folder list [--library]

screenrig media folder list
screenrig media folder list --library

Retourne chaque dossier du projet, au maximum 1000, ordonnés par nom : data.items avec id, name, parent_id (null à la racine de la bibliothèque) et revision. Construisez l’arborescence à partir de parent_id. Le dossier d’un fichier est folder_id sur media list et media show ; il est absent à la racine de la bibliothèque.

Lire un dossier de médias.

media folder show <id>

screenrig media folder show mfd_01EXAMPLEFOLDER000000000

L’enveloppe transporte le name, parent_id et revision du dossier.

Créer un dossier de médias à la racine de la bibliothèque ou dans un autre dossier.

media folder create --name NAME [--parent ID]

screenrig media folder create --name Menus
screenrig media folder create --name Lunch --parent mfd_01EXAMPLEFOLDER000000000

Une organisation contient au maximum 1000 dossiers, tous projets confondus, imbriqués jusqu’à 10 niveaux. Une liste de lecture joue les fichiers d’un dossier avec un sélecteur by:folder.

Renommez un dossier de médias, ou déplacez-le avec tout son contenu dans un autre dossier.

media folder update <id> [--name NAME] [--parent ID | --root] [--expect-rev REVISION]

screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --name Archive
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --root

Un dossier ne peut pas être déplacé dans lui-même ou dans un dossier qu’il contient, et un déplacement doit garder chaque dossier dans une profondeur maximale de 10 niveaux. Envoyer les valeurs actuelles est une opération sans effet.

Supprimer un dossier média. Ses fichiers et dossiers sont déplacés d’un niveau vers le haut.

media folder delete <id> [--expect-rev REVISION]

screenrig media folder delete mfd_01EXAMPLEFOLDER000000000

Supprime uniquement le dossier. Ses fichiers et dossiers montent dans son parent, ou dans la racine de la bibliothèque s’il n’en a pas. Un sélecteur by:folder qui le nomme ne correspond plus à rien, donc redirigez d’abord ces listes de lecture.