Intégrations : YouTube, Discord, dashboard, Streamlabs et RCON

Petits services du SDK vers des plateformes tierces. Partagés appli + widget, sauf RCON (appli uniquement). Les scopes indiqués ne concernent que les applis (permissions). Les méthodes réseau sont async : prévoir leur échec.

kapp.youtube

• await kapp.youtube.video(videoId) renvoie une ressource vidéo, ou null lorsqu'elle est introuvable ou indisponible. La ressource porte id, kind, etag, snippet (titre, description, chaîne, miniatures…) et status (notamment embeddable, privacyStatus). Seules les parties snippet,status sont demandées : ni durée ni statistiques ne sont fournies. Les tailles de miniatures et les métadonnées optionnelles peuvent manquer.
• await kapp.youtube.playlistVideos(playlistId) renvoie directement une liste de 50 entrées au maximum, sans enveloppe items ni pagination. Une entrée de playlist porte id, kind, etag et snippet. Son id identifie l'entrée ; l'identifiant de la vidéo est snippet.resourceId.videoId. Les informations du propriétaire peuvent manquer, notamment pour les vidéos privées ou supprimées.

Les réponses sont typées dans les déclarations distribuées (VideoData, PlaylistVideoData, PlaylistVideosData). Ce sont des données YouTube relayées par le serveur ; elles ne garantissent pas qu'une vidéo pourra être lue dans un lecteur intégré.

const video = await kapp.youtube.video('video-id');
if (video) {
    await kapp.chat.say(video.snippet.title);
}
const entries = await kapp.youtube.playlistVideos('playlist-id');
const videoIds = entries.map(entry => entry.snippet.resourceId.videoId);

Formats amont : vidéos YouTube et entrées de playlist. Les types Kappapps décrivent uniquement les parties demandées par le serveur.

Lecteur intégré

await kapp.youtube.embed(videoId, options?) ajoute un lecteur au body de la page de l'appli ou du widget et renvoie l'instance native YT.Player, typée YoutubePlayer. Chaque appel crée un lecteur distinct. Les appels successifs ou simultanés partagent le chargement initial de l'API YouTube dans cette page ; une API déjà prête est réutilisée immédiatement.

La Promise se résout dès la construction du lecteur. Attendre son événement onReady pour utiliser les commandes de lecture. Les callbacks reçoivent leur lecteur dans event.target ; onStateChange fournit aussi l'état numérique dans event.data (-1 non démarré, 0 terminé, 1 lecture, 2 pause, 3 chargement, 5 prêt à lire).

const player = await kapp.youtube.embed('video-id', {
    autoplay: false,
    onReady: event => event.target.playVideo(),
    onStateChange: event => {
        if (event.data === 0) event.target.destroy();
    },
});
// Conserver player pour le retirer plus tard avec player.destroy().

Les contrôles YouTube sont masqués et le lecteur occupe 100 % de son conteneur. autoplay vaut false par défaut ; les restrictions du navigateur et de la vidéo restent applicables. Le type distribué décrit les commandes usuelles du lecteur (playVideo, pauseVideo, seekTo, loadVideoById, volume, getIframe, destroy…), sans envelopper ni modifier l'objet YouTube.

Une erreur de chargement de l'API rejette les appels en attente ; sans signal de disponibilité, ils rejettent au bout de 15 secondes. Le SDK libère cette attente et retire les scripts de son chargement en cas d'échec, ce qui permet de réessayer par un nouvel appel explicite, y compris si le second script chargé par YouTube a échoué. Les scripts déjà présents appartenant à un autre consommateur sont conservés. Ce délai concerne le chargement de l'API, pas la lecture ou l'événement onReady d'une vidéo. Voir l'API des lecteurs YouTube.

kapp.discord

• await message(webhook, message) : publie message (500 caractères au plus) sur un webhook Discord, sous le nom du bot du channel (ou « Kappapps »). Un webhook invalide ou expiré répond 502. Appli : scope discord:message.

L'appli fournit son propre webhook, en général via une préférence string avec confidential: true. Le webhook d'une annonce configurée, lui, ne quitte jamais le serveur : pour diffuser une annonce existante, utiliser annonces.

kapp.dashboard

• await customEvent(title, message = null) : ajoute un événement au fil du dashboard du streamer. title de 1 à 100 caractères, message jusqu'à 255. Appli : scope dashboard-event:create.

kapp.streamlabs

Relaie les événements du socket Streamlabs du streamer, si celui-ci a renseigné sa clé de socket Streamlabs dans les réglages de son channel. Aucun appel réseau.

kapp.streamlabs.events.on(kapp.streamlabs.EVENTS.DONATION, (donations) => {
    for (const donation of Array.isArray(donations) ? donations : []) {
        kapp.chat.say(`Merci ${donation.name} pour ${donation.formatted_amount} !`);
    }
});

Le nom d'événement est le type envoyé par Streamlabs (donation, et les autres types de son socket) ; les données sont son champ message, transmis tel quel, en général une liste. Sans clé configurée, aucun événement n'arrive. Vérifier les champs avant usage.

kapp.rcon (appli uniquement)

• await send(host, port, password, command) : envoie une commande RCON (protocole Source) à un serveur de jeu et renvoie sa réponse texte. port est un entier. Connexion limitée à 2 s ; échec d'authentification, de paquet ou de connexion : 400 avec le message d'erreur. Un widget reçoit 403.

Le mot de passe transite par le serveur Kappapps : le faire saisir par le streamer dans une préférence confidential, jamais en dur dans le code.