Compositions média

Disponible dans le SDK app/widget V2 à jour, via kapp.medias. Le moteur est commun à l’aperçu du formulaire et à l’overlay. Il ne décide jamais des déclenchements, priorités, superpositions ou files d’attente des widgets.

Contrôle de lecture

• await kapp.medias.playClip(file, options) joue un ChannelMediaFileData ou {url, type} (sounds, videos, images). Les options sont les champs d’un Clip, sauf id, fileId et source.
• await kapp.medias.playComposition(document) joue un CompositionV1.
• Ces appels résolvent quand le premier élément est prêt et la lecture démarrée. Ils retournent un MediaPlayback avec pause(), resume(): Promise<void>, stop() et finished.
• await playback.finished donne {reason: 'ended'} à la fin naturelle ou {reason: 'stopped'} après arrêt volontaire. Les erreurs rejettent les promesses. La fermeture du widget annule aussi ses chargements et lecteurs.
• Un lecteur libère uniquement ses propres ressources. Ne jamais fermer kapp.medias.audioContext pour arrêter une composition.
• Une image seule reste cinq secondes par défaut ; un son/une vidéo se termine naturellement. Une boucle infinie de playClip reste active jusqu’à stop().

Les médias sont préparés avant leur démarrage. Une horloge commune pilote les éléments et animations ; les fichiers et buffers décodés sont réutilisés au fil des répétitions. Un refus d’autoplay, un échec CORS/codec ou un fichier manquant constitue une erreur explicite. Les vidéos utilisent Web Audio ; leur serveur doit autoriser CORS. Les images seules ne demandent pas de déverrouillage audio.

Document versionné

Les champs requis sont décrits par les types publiés CompositionV1, Scene, Clip et ClipAnimation. L’ordre des tableaux est l’ordre de lecture et des calques. Les id sont uniques dans tout le document, stables pendant les modifications, composés de lettres ASCII, chiffres, _ ou - (80 caractères maximum).

Niveau	Champs
Composition	version: 1, mode: 'sequence' | 'random', repeat, scenes: Scene[]
Scène	id, name, duration: 'auto' | 'infinite' | nombre, repeat, clips: Clip[]
Élément	id, name, fileId, at, duration, repeat, trim, volume, position, animation, portraitAnimation?

random tire une scène entière : ses images et sons restent associés. Chaque nouvelle répétition de la composition refait le tirage. repeat vaut le nombre total de lectures (1 à 10 000) ou 'infinite', à chaque niveau.

Tous les temps sont en millisecondes (0 à 86 400 000), y compris les points clés. Les durées fixes sont positives.

• trim: {start, end} sélectionne un extrait source ; end: null signifie la fin du fichier. Chaque boucle relit cet extrait.
• at est le démarrage de l’élément dans sa scène, indépendant de l’extrait.
• duration: 'natural' utilise l’extrait entier. Une durée numérique borne chaque lecture ; une image peut ainsi rester 5 000 ms.
• duration: 'scene' remplit la scène sans contribuer à sa durée automatique. duration: 'infinite' reste sans fin propre. Pour répéter un son/une vidéo jusqu’à la fin de la scène, choisir aussi repeat: 'infinite'.
• La durée automatique est le maximum des fins finies des autres éléments, décalage at compris. Sans élément déterminant une fin, choisir une durée de scène fixe ou 'infinite'.
• Une scène fixe coupe tous ses éléments à son terme. Une scène permanente attend un arrêt explicite. Une scène vide automatique se termine immédiatement ; une répétition infinie de scène vide est refusée à la lecture.

Fichiers et placement

Dans un widget enregistré, fileId désigne l’identifiant numérique permanent d’un fichier du channel. Les URL/métadonnées sont résolues à la lecture. Un remplacement garde la référence ; une suppression laisse un élément manquant à réparer. fileId: null est un emplacement non configuré et ne peut pas être joué. Les fichiers temporaires du dossier apps doivent d’abord être conservés dans les fichiers personnels.

Une appli peut fournir source: {url, type} pour ses propres assets ; dans ce cas fileId peut être null. Le formulaire serveur ne conserve jamais source envoyé par un client. Sans source, la résolution par identifiant passe par l’API média du channel et exige le scope file:read pour une appli.

position: {x,y,w,h,portrait?} utilise les règles de placement existantes : référence horizontale 1920 × 1080, variante verticale 1080 × 1920. Sans variante, le cadre horizontal est réduit et centré. Les fichiers et la chronologie restent communs aux deux formats.

Animations

animation: {duration, repeat, keyframes} anime les valeurs suivantes. Un point contient at et les propriétés qu’il modifie :

• x, y : translation relative au placement ; rotation : degrés ; scale : facteur, de 0 à 100.
• opacity et volume : multiplicateurs de 0 à 1. Le volume de base du clip reste entre 0 et 100.
• easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' contrôle l’arrivée au point clé.

Les points sont triés par temps, sans doublon, et compris dans la durée de l’animation. Une propriété absente n’écrase pas les autres pistes. Les valeurs neutres sont translation/rotation 0, échelle/opacité/volume 1. Après les répétitions finies, le dernier état reste appliqué. Les répétitions de l’animation et du fichier sont indépendantes.

Les préréglages fondu, glissement, zoom, rebond et fondu audio produisent de simples points clés éditables. portraitAnimation remplace l’animation en format vertical, sans dupliquer les médias. Sans variante, les translations horizontales sont réduites proportionnellement en portrait.

Limites : 60 scènes, 120 éléments au total, 200 points par animation ; noms de 255 caractères maximum. Les coordonnées et rotations sont bornées entre −10 000 et 10 000 ; largeur/hauteur entre 1 et 10 000.

Formulaire, assistant et compatibilité

Le parcours simple propose un fichier et ses réglages. « Composer » ouvre scènes, calques, pistes et points clés. L’aperçu lit le brouillon seul : il n’enregistre rien et ne lance pas le script, les annonces ou les autres actions du widget.

L’agent lit get_widget_config.media_settings, puis prépare configure_widget_composition {composition, media_enabled?}. Le document est complet : conserver les scènes/éléments non demandés et leurs identifiants. Les changements ne sont appliqués qu’après submit_widget, avec détection des modifications concurrentes. configure_widget_medias reste réservé à l’ancienne collection ; il ne convertit pas un widget. Tout nouveau widget IA expose déjà le mode composition, même avant son enregistrement. Une création éphémère peut soumettre une composition non vide avec media_enabled: true, sans code.

La composition est disponible pour tous les channels, sans activation Feature. Les nouveaux widgets vierges utilisent ce format avec le SDK V2. Les widgets existants, leurs copies et les anciens modèles gardent leur format média et leur édition historique. La conversion est explicite : brouillon, aperçu, enregistrement, sauvegarde serveur de la configuration et du SDK d’origine. Un retour arrière restaure cet instantané et termine la conversion ; une conversion ultérieure repart des réglages historiques alors présents et crée une nouvelle sauvegarde. Les cas V1 dont les comportements ne peuvent pas être reproduits fidèlement proposent une copie V2, en conservant l’original. Les bundles V1 restent figés.

Le flowchart propose Composition et Play Composition ; l’action attend finished et distingue fin, arrêt et erreur. Les nœuds média historiques restent disponibles. Ne pas activer à la fois l’autolecture de la composition et une action qui rejoue cette même composition.