Kappapps SDK

Appearance

kapp.medias ​

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.

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.

js
// 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) ​

js
// 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.