kapp.medias

Placement horizontal et vertical

Un média de préférence garde position: {x,y,w,h,portrait?: {x,y,w,h}|null}. playMedia et KMedia résolvent ce placement et déplacent les images/vidéos en cours sans recommencer la lecture. Sans variante, le placement horizontal est réduit et centré. Une écriture omettant portrait conserve la variante ; portrait:null la supprime. Fichier, volume et timeline restent communs. Voir le guide vertical.

Les positions explicites des options de lecture, de playImage/playVideo ou de setPosition utilisent les pixels logiques du cadre courant, sans conversion automatique. Le parent applique déjà le zoom. Ne multipliez pas par kapp.overlay.layout.scale.

Jouer des sons, images et vidéos sur l'overlay. Pluriel : kapp.medias (pas kapp.media).

Service partagé appli + widget : API identique.

Quand l'utiliser (vs alternative)

• Préfère kapp.medias.* à un <audio> / <video> brut en HTML : c'est routé vers le bon contexte overlay et géré par le moteur.
• Pour jouer un média déjà uploadé sur le channel : récupère son chemin (kapp.medias.get(name).path, ou l'outil list_channel_medias côté agent widget), puis passe-le à playAudio/playImage/playVideo.

Méthodes

• playAudio(source: string, volume = 50, effects: KAudioEffect[] = []): Promise<KAudio> — joue un son. volume 0-100. async.
• playImage(source: string, position = {}): Promise<KImage> — affiche une image. position: {x?, y?, w?, h?} (px). async.
• playVideo(source: string, volume = 50, position = {}): Promise<KVideo> — joue une vidéo. async.
• playMedia(media: MediaData, options = {}): Promise<KMedia> — avancé : media = objet MediaData complet ({file, volume, position, timeline}), pas un simple chemin.
• get(name: string): Promise<ChannelMediaFileData | null> — métadonnées d'un média du channel par nom ({path, name, type, extension, …}). async.
• all(): Promise<ChannelMediaFileData[]> — tous les médias du channel. async.
• library(): Promise<LibraryMediaFileData[]> — tous les assets publiés de la bibliothèque publique Kappapps. async.
• getLibrary(slug: string): Promise<LibraryMediaFileData | null> — un asset public par son slug (identifiant stable, ex. kapp-ding). null si inconnu ou dépublié. async.
• playLibrary(slug: string, options = {}): Promise<KMedia | null> — joue directement un asset public par slug (son/vidéo/image selon son type). null si le slug ne résout pas. async.

Timeline

• timeline.startAt et timeline.endAt sont exprimés en millisecondes.
• Sans endAt, un son ou une vidéo va jusqu'à sa fin naturelle ; une image reste affichée jusqu'à stop() ou jusqu'à la fermeture du widget.
• Une fin nulle, négative ou antérieure au début est ignorée afin de ne jamais créer un média de durée nulle.

Bibliothèque publique Kappapps

Des assets prêts à l'emploi (soundboards, images, vidéos) fournis par Kappapps, jouables sur n'importe quel channel sans aucun upload — l'asset est servi directement depuis le CDN, il n'est pas copié chez le streamer.

LibraryMediaFileData = ChannelMediaFileData + {slug, category, tags}. Le slug est l'identifiant stable à utiliser dans le code et dans les prefs.

// Jouer un son de la bibliothèque publique
await kapp.medias.playLibrary('kapp-ding', { volume: 70 });

// Parcourir le catalogue (assets publiés uniquement)
const sounds = (await kapp.medias.library()).filter(a => a.type === 'sounds');

Un item de préférence mediaFile peut aussi avoir un asset public comme valeur par défaut (default: { library: 'kapp-ding' }) — voir preferences.md.

KAudioEffect (tableau d'effets pour playAudio) : radio, echo, slow, fast, left, right, half_speed, double_speed, double_pitch, half_pitch, neighbor, reverb, robot, disto, high, low.

Exemple (V2, exécutable)

// Joue un son existant du channel à 70% + un effet radio
const media = await kapp.medias.get('coin');
if (media) {
    await kapp.medias.playAudio(media.path, 70, ['radio']);
}

Pièges

• C'est playAudio / playImage / playVideo qui prennent un chemin (string). playMedia prend un objet MediaData complet — ne lui passe pas le résultat brut de get() sans le wrapper.
• source = le path renvoyé par kapp.medias.get(name).path. N'invente pas de chemin.
• volume est sur 0-100.
• Slug ≠ name : get(name) cherche dans les médias du channel par nom de fichier ; getLibrary(slug) / playLibrary(slug) cherchent dans la bibliothèque publique par slug. Ne les mélange pas.
• playLibrary renvoie null (pas d'exception) si le slug est inconnu ou dépublié — gère ce cas.
• Un asset dépublié disparaît de library()/getLibrary() mais reste jouable via une pref qui le référençait déjà.
• V1 mort : kapp.playMedia(file) / kapp.media.play({url, volume}) n'existent plus.