🧩 Créer un module

🌱 Par où commencer si tu débarques

Pas de panique. Tu n'as pas besoin d'être informaticien·ne pour créer un module OpenOverlay. Un module c'est simplement un petit programme qui dit à ton overlay quoi faire quand quelque chose se passe sur ta chaîne. Et ce "petit programme", ça ressemble à des instructions écrites en anglais simplifié — pas si différent d'une recette de cuisine.

Ce dont tu as besoin

🗺️ Les concepts clés

Avant de plonger dans le code, voici comment fonctionne OpenOverlay en quelques mots.

L'overlay et l'admin : deux mondes séparés

OpenOverlay tourne sur deux pages différentes en même temps dans ton navigateur. La page overlay est celle que tu captures dans OBS — c'est ton stream. La page admin est le tableau de bord où tu configures tout. Ces deux pages communiquent ensemble en temps réel.

Un module, c'est quoi concrètement ?

Un module est un dossier avec 4 fichiers minimum. Chaque fichier a un rôle précis :

• manifest.json — la carte d'identité du module. Son nom, sa description, ses réglages par défaut. Pas de code ici, juste des données.
• overlay.html — ce que tu veux afficher sur le stream. Comme construire une maison vide que tu vas ensuite meubler avec le code.
• overlay.js — le code qui s'exécute sur le stream. C'est lui qui "écoute" les événements Twitch et anime l'overlay.
• admin.js — le code qui construit l'interface de configuration dans le tableau de bord.

Les "hooks" : brancher sur ce qui se passe

Un hook, c'est une fonction que tu déclares une fois, et OpenOverlay l'appelle automatiquement quand quelque chose se passe. C'est comme brancher une prise — tu prépares le câble, et l'électricité coule quand il y en a.

📁 Structure d'un module

Un module est un dossier dans mods/. Son nom de dossier correspond à son identifiant unique.

manifest.json — la carte d'identité

{
  "id":          "mon_module",
  "name":        "Mon Module",
  "description": "Ce que fait mon module en une phrase",
  "icon":        "✨",
  "types":       ["display"],
  "configKey":   "mon_module",
  "defaultConfig": {
    "enabled": true,
    "message": "Bonjour !",
    "volume":  1.0
  },
  "version": "1.0.0",
  "author":  "TonPseudo",
  "files": ["manifest.json", "overlay.js", "overlay.html", "admin.js"]
}

🎬 Module overlay (overlay.js)

C'est le cœur de ton module — le code qui tourne sur la page stream et qui réagit à ce qui se passe sur Twitch. Tu déclares ton module avec OO.Mods.register() en lui passant un objet qui contient toutes tes réponses aux événements.

OO.Mods.register({
  id: 'mon_module',

  // Appelé avant init() avec l'état précédemment sauvegardé (ou null)
  onStateRestore(data, api) { },

  // Appelé une fois au démarrage
  init(api) { },

  // Appelé quand le streamer sauvegarde ses réglages
  onConfigReload(api) { },

  // Appelé à chaque événement Twitch (follow, sub, raid…)
  onTwitchEvent(type, event, api) { },

  // Appelé quand un message commence par ! dans le chat
  onChatCommand(cmd, args, api, sender) { },

  // Appelé quand un viewer envoie son premier message
  onFirstChatter(username, isFirstEver, api) { },

  // Appelé quand l'admin envoie un message à l'overlay
  onAdminMessage(data, api) { },
});

Hooks d'événements — le détail

onStateRestore(data, api) ≥ 1.45.0

Appelé automatiquement par le core avant init(), avec les données précédemment sauvegardées via api.saveState() — ou null si aucune donnée n'existe. Utilise ce hook pour restaurer l'état d'affichage (scène active, file, score…) sans appel réseau bloquant dans init().

onStateRestore(data, api) {
  if (!data) return;
  this._score = data.score ?? 0;
  this._active = data.active ?? null;
  // Ne pas déclencher d'effets visuels ici — init() s'en charge
},

init(api)

Appelé une seule fois, après que tout est chargé et connecté. C'est le bon endroit pour démarrer un timer, écouter des événements DOM, ou initialiser des variables d'état.

onConfigReload(api)

Déclenché quand le streamer clique sur "Sauvegarder" dans le dashboard. Utilise ce hook pour relire la configuration et adapter l'overlay sans tout recharger.

onTwitchEvent(type, event, api)

C'est l'événement le plus important. Il est appelé pour chaque notification Twitch : un follow, un sub, un raid, des bits, un échange de points de chaîne… Le paramètre type est une chaîne de caractères qui dit quel événement c'est. Le paramètre event est l'objet avec toutes les données.

onTwitchEvent(type, event, api) {
  if (api.config.mon_module?.enabled === false) return;
  if (type !== 'channel.follow') return;
  console.log('Nouveau follow de', event.user_name);
},

onChatCommand(cmd, args, api, sender)

Appelé pour chaque message du chat qui commence par !. cmd est la commande en minuscules (ex : '!salut'), args est un tableau avec les mots qui suivent. sender décrit qui a envoyé le message.

onFirstChatter(username, isFirstEver, api)

Déclenché quand un viewer envoie un message pour la première fois. isFirstEver est true si c'est son tout premier message depuis la création de la chaîne.

onAdminMessage(data, api)

Appelé quand l'admin envoie quelque chose à l'overlay via tools.sendToOverlay(). Utilise data.type pour distinguer tes différents messages.

L'objet api

overlay.html — construire la scène

Ce fichier est inséré dans la page stream au chargement. Il contient les éléments HTML que ton module va animer. Ils sont invisibles au départ (classe hidden) et ton JavaScript les rend visibles au bon moment.

Règle d'or : préfixe tous tes identifiants avec le nom de ton module pour éviter les conflits.

<!-- overlay.html -->
<div id="mon-module-panel" class="hidden">
  <div id="mon-module-texte"></div>
</div>

⚙️ Module admin (admin.js)

Ce fichier construit l'interface de configuration qui apparaît dans le tableau de bord. C'est là que le streamer règle les messages, les sons, les couleurs de ton module.

OO.Admin.register({
  id: 'mon_module',

  render(config, container, tools) {
    if (!config.mon_module) config.mon_module = {};
    const cfg = config.mon_module;

    container.innerHTML = `
      <div class="card">
        <div class="card-body">
          <div class="field">
            <label>Message</label>
            <input type="text" id="mm-msg" value="${cfg.message ?? ''}">
          </div>
        </div>
      </div>`;

    container.querySelector('#mm-msg').oninput = e => {
      cfg.message = e.target.value;
      tools.markDirty();
    };
  },

  getCommands(config) {
    const permission = config.commandPermission ?? 'streamer';
    return [
      { cmd: '!macommande', args: '[texte]', desc: 'Affiche quelque chose sur le stream', permission },
    ];
  },
});

L'objet tools

onOverlayMessage(payload) ≥ 1.37.0

Hook optionnel sur le module admin. Appelé quand l'overlay envoie un état via api.sendToAdmin(modId, payload). Uniquement déclenché si le mod est la section active du dashboard. Permet d'afficher un panel live (file d'attente, score, état…) sans polling ni localStorage.

onOverlayMessage(payload) {
  // payload = ce que l'overlay a passé dans api.sendToAdmin('mon-mod', payload)
  const panel = this._container?.querySelector('#mon-panel');
  if (panel) this._render(panel, payload);
},

💾 Persistance d'état

Par défaut, l'état d'un module (file active, scène en cours, score…) est perdu quand l'overlay se recharge. Pour les modules avec un état métier significatif, OpenOverlay propose deux mécanismes : la sauvegarde explicite et la restauration automatique.

Sauvegarder depuis l'overlay

// Fire-and-forget — aucun retour à attendre
api.saveState('mon_module', { score: 42, activeSlot: 'intro' });

// Chargement explicite (async) — rare, préférer onStateRestore
const data = await api.loadState('mon_module');

Sauvegarder depuis l'admin

// Fire-and-forget
tools.saveModState('mon_module', { mode: 'gaming', queue: [] });

// Chargement (async) — ex : polling cross-device
const data = await tools.loadModState('mon_module');

Restauration automatique — hook onStateRestore

Le hook onStateRestore(data, api) est appelé par le core avant init(), avec les données précédemment sauvegardées — ou null. C'est l'endroit idéal pour restaurer l'état sans appel réseau bloquant.

OO.Mods.register({
  id: 'mon_module',
  _score: 0,
  _active: null,

  onStateRestore(data, api) {
    if (!data) return;
    this._score  = data.score  ?? 0;
    this._active = data.active ?? null;
    // Ne pas déclencher d'effets visuels ici — init() s'en charge
  },

  init(api) {
    // À ce stade, this._score et this._active sont déjà restaurés
    this._render(api);
  },

  _someAction(api) {
    this._score++;
    this._render(api);
    api.saveState('mon_module', { score: this._score, active: this._active });
  },
});

⚙️ Système de configuration

La configuration de l'utilisateur est un grand objet JSON stocké côté serveur. Chaque module occupe une clé, définie par configKey dans le manifest.

Au démarrage, OpenOverlay fusionne intelligemment trois sources (du moins au plus prioritaire) :

1. Le fichier config.json global
2. Le defaultConfig du manifest
3. La configuration sauvegardée par l'utilisateur

La fusion est profonde : si l'utilisateur n'a changé que le volume, les autres champs viennent de ton defaultConfig. Exception : les tableaux sont remplacés entièrement.

onTwitchEvent(type, event, api) {
  const cfg = api.config.mon_module;
  if (cfg?.enabled === false) return;
  const message = cfg?.message ?? 'Valeur par défaut';
  const volume  = cfg?.volume  ?? 1.0;
},

📡 Référence des événements Twitch

OpenOverlay s'abonne automatiquement à ces événements dès le démarrage. Tu les reçois tous dans onTwitchEvent(type, event, api).

Événements étendus

Ces événements sont disponibles via onTwitchEvent() pour les mods tiers. Les mods intégrés ne les utilisent pas.

💬 Commandes chat

Chaque message qui commence par ! déclenche onChatCommand() sur tous les modules. Il n'y a pas de routage exclusif — plusieurs modules peuvent répondre à la même commande.

onChatCommand(cmd, args, api, sender) {
  if (api.config.mon_module?.enabled === false) return;
  if (!api.checkPermission(sender, 'streamer')) return;
  if (cmd !== '!macommande') return;
  const texte = args.join(' ');
  api.sendChat(`Commande reçue : ${texte}`);
},

Niveaux d'accès

Utilise api.checkPermission(sender, level) — ne lis jamais les propriétés de sender directement.

Le flag sender._viaChannelPoints

Quand une commande est déclenchée par une récompense de points de chaîne (et non par un message dans le chat), le sender reçu contient _viaChannelPoints: true. Cela te permet de traiter ces deux origines différemment.

onChatCommand(cmd, args, api, sender) {
  if (sender._viaChannelPoints) {
    // Déclenché par un échange de points — login du viewer dans sender.login
  }
},

Déclencher une commande programmatiquement

Depuis un mod overlay, tu peux déclencher une commande sans passer par le chat :

// Via l'objet api (recommandé)
api.trigger('!alerte', ['follow', 'Alice']);

// Via événement DOM (depuis n'importe quel script de la page)
document.dispatchEvent(new CustomEvent('oo:cmd', {
  detail: { cmd: '!alerte', args: ['follow', 'Alice'] }
}));

🗂️ Assets utilisateur

Chaque utilisateur dispose d'un espace de stockage personnel pour ses fichiers (GIFs, sons, images, vidéos), accessible depuis la section Outils → Mes fichiers du dashboard. Ces fichiers sont référencés avec le préfixe user:// dans la config, et résolus vers leur URL complète au moment de l'utilisation.

Limites : 4 Mo par fichier et 50 fichiers par utilisateur (l'écrasement d'un fichier existant reste toujours possible). Un upload au-delà du quota est refusé avec une erreur explicite — gère ce cas dans tes mods en affichant le message d'erreur retourné par uploadAsset.

Pour les champs de sélection dans l'admin, utilise toujours createAssetField — il combine le sélecteur (assets intégrés + fichiers uploadés), le bouton d'upload et un aperçu automatique (miniature pour les images/GIFs, lecteur audio pour les sons, aperçu vidéo pour les vidéos).

// Dans le template HTML :
<div class="field">
  <label>Son</label>
  <div id="mon-sound-field"></div>
</div>

// Après container.innerHTML :
container.querySelector('#mon-sound-field').replaceWith(
  createAssetField({
    type: 'sound', // 'image', 'gif' ou 'sound'
    value: cfg.sound ?? '',
    onChange: (path) => { cfg.sound = path; markDirty(); },
  })
);

const soundPath = cfg?.sound;
if (soundPath) {
  const url = api.resolveAsset(soundPath);
  api.playSound(url, cfg.volume ?? 1);
}

🔗 Communication inter-modules

Les modules overlay peuvent se parler via l'objet api, sans jamais accéder à OO.Mods directement. Deux méthodes sont disponibles :

// Diffuser un événement custom à tous les mods
api.emit('onMyCustomEvent', { data: 'valeur' });

// Déclencher une commande chat depuis un autre mod ou depuis l'admin
api.trigger('macommande', ['arg1']);
api.trigger('macommande', [], { isBroadcaster: false, isMod: true });

Cibler un mod spécifique

Pour appeler une méthode publique d'un autre mod directement, sans passer par un broadcast :

// Accès direct au mod alerts via api.getMod()
const alerts = api.getMod('alerts');
alerts?.queue('follow', { username: 'Alice' });

🧰 Utilitaires partagés (OO.*)

L'objet global OO expose des utilitaires partagés entre tous les mods. Ils sont disponibles dans overlay.js et admin.js sans import.

Conventions de nommage du système : les clés localStorage du core sont préfixées oo_, les événements DOM oo: (ex. oo:cmd), et le canal admin ↔ overlay s'obtient via la constante OO.CHANNEL.

OO.CHANNEL — canal admin ↔ overlay

Nom du BroadcastChannel reliant le dashboard et l'overlay. Si ton module doit instancier le canal lui-même (cas rare — préfère tools.sendToOverlay côté admin et onAdminMessage côté overlay), utilise toujours cette constante, jamais une chaîne en dur.

const bc = new BroadcastChannel(OO.CHANNEL);

OO.Mods.all() — accès à tous les mods

Retourne le tableau de tous les mods enregistrés. À utiliser uniquement quand api.getMod(id) ou api.emit() ne suffisent pas (cas avancés : introspection, méta-commandes…).

const mods = OO.Mods.all(); // Array des mods enregistrés

OO.fmt(tpl, vars) — templating

Remplace les tokens {clé} dans un template par les valeurs de l'objet vars. Les tokens inconnus sont remplacés par une chaîne vide.

OO.fmt('{username} a envoyé {amount} bits !', {
  username: 'Alice',
  amount:   100,
});
// → "Alice a envoyé 100 bits !"

OO.semverCompare(a, b) — comparaison de versions

Compare deux versions semver ("1.24.0"). Retourne -1 si a < b, 0 si égales, 1 si a > b. C'est la fonction utilisée par le Store pour vérifier minSystemVersion.

OO.semverCompare('1.9.3', '1.24.0'); // → -1 (tri numérique, pas alphabétique)

OO.escHtml(str) — sécurité DOM

Échappe les caractères spéciaux HTML avant une insertion dans innerHTML. Gère null et undefined (retourne une chaîne vide).

container.innerHTML = `<span>${OO.escHtml(userName)}</span>`;

OO.anim(el, keyframes, options) — animations

Wrapper Promise autour de Element.animate(). Se résout quand l'animation se termine ou est annulée.

await OO.anim(box, [
  { transform: 'scale(0)' },
  { transform: 'scale(1)' },
], { duration: 300, easing: 'cubic-bezier(0.22,1,0.36,1)' });

OO.setVolume(volume) — volume global du son ≥ 1.58.0

Multiplicateur de volume (0-1) appliqué à tous les sons joués via OO.playSound/api.playSound, y compris ceux déjà en cours de lecture. N'est pas destiné aux mods — prévu pour un hôte natif qui embarque une page OpenOverlay dans une WebView (ex. l'app ChatCast embarquant /overlay-audio) et veut piloter le volume du mix depuis son UI native, via un pont JS (window.OO.setVolume(0.5)). N'affecte pas le volume système.

OO.setVolume(0.5); // tous les sons désormais joués à 50% de leur volume configuré

OO.AlertBox — thèmes, animations et logo ≥ 1.49.0

Utilitaire partagé par tous les mods utilisant une boîte d'alerte. Lit le style configuré dans Préférences → Styles graphiques (animation, thème, couleur d'accent, animation logo) et l'applique automatiquement. Depuis la v1.50.0, gère aussi l'animation du logo d'overlay.

Thèmes disponibles : glass (défaut, arrondi 14px), solid (angles vifs 4px), neon (arrondi 22px), minimal (bande avec bordure gauche), bd (bulle BD arrondie 48px avec queue).
Animations : pop (défaut), slide-top, slide-left, slide-right.
Animation logo : activée via logoThrough: true dans config.alert_style (configurable dans Préférences).

OO.AlertQueue — file d'alertes séquentielles

Classe qui gère une file d'attente d'alertes : chaque alerte attend la fin de la précédente avant de s'afficher. Inclut un counter de génération pour annuler proprement les alertes en cours si clear() est appelé.

Depuis la v1.49.0, accepte un second argument opts optionnel. Depuis la v1.50.0, opts.withLogo active la séquence logo complète : arc → animIn box → sortie logo → showFn → animOut box → fondu logo. Le showFn n'a alors besoin que de peupler le contenu et d'attendre la durée. clear() gère automatiquement l'annulation de la box et du logo.

// Mode automatique avec logo (recommandé — alerts, channel_points)
init(api) {
  this._alertQueue = new OO.AlertQueue(
    async (data, isCurrentGen) => {
      // Peupler le contenu et attendre la durée — animations gérées par la queue
      document.getElementById('mon-titre').textContent = data.title;
      await new Promise(r => setTimeout(r, data.duration ?? 5000));
    },
    {
      box:       document.getElementById('ma-box'),
      getPrefix: () => this._getPositionPrefix(api),
      withLogo:  true,   // active l'animation logo partagée
    }
  );
},

api.placeInZone(zoneId, element) — zones d'emplacement

Place (ou déplace) un élément DOM dans l'un des 9 conteneurs de zone de l'overlay. Le conteneur se charge du positionnement ; si plusieurs modules occupent la même zone, ils s'empilent automatiquement en colonne ou en ligne selon la configuration du dashboard.

// overlay.js — placer le widget dans la zone configurée
init(api) {
  const cfg = api.config?.mon_module ?? {};
  api.placeInZone(cfg.position ?? 'top-right', document.getElementById('mon-widget'));
},

onConfigReload(api) {
  const cfg = api.config?.mon_module ?? {};
  // appendChild déplace l'élément si la position a changé
  api.placeInZone(cfg.position ?? 'top-right', document.getElementById('mon-widget'));
}

Variables CSS système

OpenOverlay expose des variables CSS globales sur :root que les modules peuvent lire — ou écrire — pour se coordonner sans passer par des événements JS.

Pour qu'un élément positionné en bas s'écarte automatiquement quand une barre système est active, utilise calc() avec la variable :

/* overlay.css */
#mon-widget {
  position: fixed;
  bottom: calc(16px + var(--oo-safe-bottom));
  right: 16px;
}

Si ton module crée lui-même une barre en bas, il doit écrire la variable pour que les autres s'adaptent :

// overlay.js — quand ta barre devient visible en bas
document.documentElement.style.setProperty('--oo-safe-bottom', '50px');

// quand elle disparaît
document.documentElement.style.setProperty('--oo-safe-bottom', '0px');

🚀 Exemple complet et commenté

Un module "Annonce de sub" — quand quelqu'un s'abonne, un panneau apparaît sur le stream avec un son. Le streamer peut configurer le message, la durée et le son depuis le dashboard.

Chaque ligne de code est commentée pour que tu comprennes exactement ce qui se passe.

{
  "id":          "sub-announce",
  "name":        "Annonce Abonnement",
  "description": "Affiche un panneau quand quelqu'un s'abonne",
  "icon":        "⭐",
  "configKey":   "sub_announce",
  "defaultConfig": {
    "enabled":  true,
    "message": "⭐ {username} vient de s'abonner !",
    "sound":   "",
    "volume":  1.0,
    "duration": 5000
  },
  "version": "1.0.0",
  "files": ["manifest.json", "overlay.js", "overlay.html", "admin.js"]
}

<div id="sa-panel" class="hidden" style="
  position: fixed; top: 50%; left: 50%;
  transform: translate(-50%, -50%);
  background: #1a1a2e; border: 2px solid #9147ff;
  border-radius: 16px; padding: 32px 40px;
  font-family: sans-serif; color: white;
  font-size: 28px; text-align: center; z-index: 9999;">
  <div id="sa-text"></div>
</div>

OO.Mods.register({
  id: 'sub-announce',
  _timer: null,

  onTwitchEvent(type, event, api) {
    const cfg = api.config.sub_announce;
    if (cfg?.enabled === false) return;
    if (type !== 'channel.subscribe' || event.is_gift) return;

    const text = (cfg?.message ?? '⭐ {username} s\'abonne !')
      .replace('{username}', event.user_name);

    if (cfg?.sound) {
      api.playSound(api.resolveAsset(cfg.sound), cfg.volume ?? 1);
    }
    this._show(text, cfg?.duration ?? 5000);
  },

  onAdminMessage(data, api) {
    if (data.type === 'sa_test') {
      this._show('⭐ TestUser vient de s\'abonner !', 3000);
    }
  },

  _show(text, duration) {
    clearTimeout(this._timer);
    const panel = document.getElementById('sa-panel');
    document.getElementById('sa-text').textContent = text;
    panel.classList.remove('hidden');
    this._timer = setTimeout(() => {
      panel.classList.add('hidden');
    }, duration);
  },
});

OO.Admin.register({
  id: 'sub-announce',

  render(config, container, { markDirty, sendToOverlay, showToast, createAssetField }) {
    if (!config.sub_announce) config.sub_announce = {};
    const cfg = config.sub_announce;

    container.innerHTML = `
      <div class="card">
        <div class="card-header no-border">
          <span class="card-title">⭐ Annonce Abonnement</span>
          <button class="btn btn-ghost btn-sm" id="sa-test">▶ Tester</button>
        </div>
        <div class="card-body grid">
          <div class="field">
            <label>Message <span class="hint">({username} = pseudo)</span></label>
            <input type="text" id="sa-msg" value="${cfg.message ?? ''}">
          </div>
          <div class="field">
            <label>Durée (ms)</label>
            <input type="number" id="sa-dur" min="1000" max="30000" step="500" value="${cfg.duration ?? 5000}">
          </div>
          <div class="field">
            <label>Son (optionnel)</label>
            <div id="sa-snd-field"></div>
          </div>
        </div>
      </div>`;

    container.querySelector('#sa-msg').oninput = e => { cfg.message  = e.target.value;          markDirty(); };
    container.querySelector('#sa-dur').oninput = e => { cfg.duration = parseInt(e.target.value); markDirty(); };

    container.querySelector('#sa-test').onclick = () => {
      sendToOverlay({ type: 'sa_test' });
      showToast('Test envoyé — l\'overlay doit être ouvert');
    };

    container.querySelector('#sa-snd-field').replaceWith(
      createAssetField({
        type: 'sound',
        value: cfg.sound ?? '',
        onChange: (path) => { cfg.sound = path; markDirty(); },
      })
    );
  },

  getCommands() { return []; },
});

🎨 Framework CSS modules

Le dashboard d'OpenOverlay charge automatiquement admin/admin.css pour chaque panneau admin. Ce fichier contient un ensemble de classes prêtes à l'emploi — un framework CSS léger que tu peux utiliser directement dans ton admin.js sans importer quoi que ce soit.

Layout & listes d'items

Pour afficher une liste d'éléments configurables (commandes, séries, récompenses…) :

<div class="mod-list-header">
  <h3>Mes éléments (3)</h3>
  <button class="btn btn-primary btn-sm">+ Ajouter</button>
</div>
<div class="mod-list">
  <div class="mod-item">
    <div class="mod-item-header">
      <span class="mod-item-icon">🎯</span>
      <span class="mod-cmd-code">!bonjour</span>
      <span class="mod-item-label">Répond bonjour</span>
    </div>
    <div class="mod-item-body">
      <!-- champs du formulaire ici -->
    </div>
  </div>
</div>

Contrôles de formulaire

Patterns courants pour les champs dans .card-body.grid ou .mod-item-body :

const { cmdField, markDirty } = tools;

// Dans le HTML template :
<div class="field">
  <label>Commande</label>
  ${cmdField('mon-cmd', cfg.commandName ?? 'bonjour', {
    placeholder: 'bonjour',
    hint: 'Description de la commande.',
  })}
</div>

// Après container.innerHTML :
container.querySelector('#mon-cmd').oninput = e => {
  cfg.commandName = e.target.value.trim().replace(/^!/, '') || 'bonjour';
  markDirty();
};

// Dans le HTML template :
<div class="field">
  <label>Image</label>
  <div id="mon-image-field"></div>
</div>

// Après container.innerHTML, remplacer le placeholder :
container.querySelector('#mon-image-field').replaceWith(
  createAssetField({
    type: 'image', // 'image', 'gif' ou 'sound'
    value: cfg.image ?? '',
    onChange: (path) => { cfg.image = path; markDirty(); },
  })
);

<div class="field field-inline">
  <div class="field-inline-label">
    <strong>Saisie requise</strong>
    <small>Le viewer doit taper un message</small>
  </div>
  <label class="toggle">
    <input type="checkbox">
    <span class="toggle-track"></span>
  </label>
</div>

Sélecteur de position et taille (overlay)

Pour les mods qui ont une position configurable sur le canvas stream :

const { posPicker, markDirty } = tools;

// Dans le HTML template :
${posPicker('mon-pos', cfg.position ?? 'top-left')}

// Après container.innerHTML, binding des clics :
container.querySelectorAll('#mon-pos .pos-btn').forEach(btn => {
  btn.addEventListener('click', () => {
    container.querySelectorAll('#mon-pos .pos-btn').forEach(b => b.classList.remove('active'));
    btn.classList.add('active');
    cfg.position = btn.dataset.pos;
    markDirty();
  });
});

📡 Intégration audio externe — /api/sound-relay ≥ 1.59.0

Contrat d'API stable pour un client natif tiers (ex. ChatCast) qui veut recevoir les sons joués par l'overlay et les rejouer lui-même avec un moteur audio natif — sans passer par une WebView. C'est le même endpoint que consomme /overlay-audio (voir guide d'utilisation) ; rien n'empêche un client natif de l'interroger directement.

Authentification

En-tête Authorization: Bearer <token> — le token Twitch du streamer, le même que celui obtenu via le lien généré depuis le dashboard (Guide d'utilisation → 🔊 Copie audio). C'est un access token OAuth Twitch classique, valide ~4 heures.

GET /api/sound-relay — recevoir les événements (long-polling)

La requête reste ouverte côté serveur jusqu'à ~8 secondes en attendant un nouvel événement avant de répondre — c'est voulu (long-polling), pas un timeout d'erreur. Configure un timeout client ≥ 15 s, et relance immédiatement une nouvelle requête dès que la réponse précédente arrive, qu'elle contienne un événement ou non.

Réponse sans événement (fin du délai d'attente, rien de nouveau) :

200 OK
{ "events": [], "lastId": 42 }

Réponse avec un ou plusieurs événements :

200 OK
{
  "events": [
    { "id": 43, "src": "https://ton-instance.netlify.app/overlay/assets/sounds/defaut.mp3", "volume": 0.8, "ts": 1720000000000 }
  ],
  "lastId": 43
}

• id — entier croissant, unique par instance. Sert de curseur : réutilise le lastId de la réponse comme since de la requête suivante.
• src — URL absolue (≥ 1.59.0), prête à être téléchargée/jouée telle quelle.
• volume — flottant 0-1, déjà résolu et borné côté serveur. Le client joue le son à ce volume, éventuellement multiplié par son propre volume maître.
• ts — epoch en millisecondes, moment où le serveur a reçu l'événement (pas nécessairement l'instant exact de lecture côté overlay — écart négligeable).

POST /api/sound-relay

Réservé à l'overlay lui-même (source de vérité — c'est lui qui pousse chaque son réellement joué). Un client tiers comme ChatCast n'a besoin que du GET.

Erreurs

403 n'existe pas sur ce endpoint : l'utilisateur concerné est déterminé uniquement par le token, il n'y a pas de paramètre user à usurper. Pas de 429 non plus pour l'instant — le long-polling borne déjà naturellement la fréquence des requêtes ; ne polle pas plus vite que la réponse précédente ne revient.

Rafraîchir le token

Le lien généré par le dashboard contient token et refresh en query params. Quand GET /api/sound-relay renvoie 401, échange le refresh token :

POST /api/token-exchange
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh>

Réponse : { "access_token", "refresh_token", "expires_in" }. Le refresh token est à usage unique (rotation Twitch) — stocke systématiquement le nouveau avant de réessayer, et évite d'appeler ce endpoint deux fois en parallèle avec le même refresh token (le second échouerait).

🔐 Modèle de confiance des modules

Un module OpenOverlay s'exécute dans la même page que l'overlay et le dashboard, avec le même niveau d'accès que le code du système. C'est ce qui rend les modules puissants — mais il faut en comprendre les implications.

Conséquences concrètes :

• Pour le streamer — installer un module revient à lui faire confiance sur son instance, comme une extension de navigateur. Les modules du Store officiel sont relus avant publication ; le Mode Développeur n'installe que du code que tu fournis toi-même (un avertissement explicite le rappelle à l'activation). N'installe en mode développeur que du code que tu as écrit ou relu.
• Pour l'auteur de module — limite-toi aux APIs documentées (api.*, tools.*) et n'envoie jamais le token ni les données du streamer vers un serveur tiers. Un module qui exfiltre des données sera refusé du Store.
• Tokens — ils sont stockés dans le localStorage du navigateur, sur l'instance personnelle du streamer (jamais sur un serveur central). Les scopes Twitch demandés sont limités au strict nécessaire au fonctionnement du système.

🚀 Publier dans le Store

Tu as créé et testé un module qui te semble prêt à être partagé ? Voici le chemin complet, de la première ligne de code jusqu'à la disponibilité dans le Store officiel.

Tester en Mode Développeur

Avant de soumettre, tu dois valider ton module sur ta propre installation. Le Mode Développeur est accessible dans les Préférences du dashboard. Une fois activé, une section "Installer un module local" apparaît. Sélectionne le dossier de ton module — le dashboard le lit, le valide et l'envoie au serveur. Recharge ensuite la page.

Critères de validation

• Absence d'exfiltration de données — pas d'envoi du token, de la config ou de données personnelles vers des serveurs tiers
• Absence d'injection de code — pas d'exécution de scripts externes non déclarés
• Respect des APIs OpenOverlay — usage des hooks et méthodes documentés ici
• Fonctionnement stable — pas d'erreurs JS non catchées, pas de boucles infinies