Lecture et lecteur

Pour chaque apprenant autorisé, votre serveur demande un lien de lecture personnel. La page de cours l’affiche dans le lecteur Vidoum.

Demander un lien

Ce lien est l’autorisationAppelez cette route uniquement après avoir vérifié, avec vos propres règles, que l’apprenant a le droit de voir la vidéo. Ne réutilisez jamais un lien pour plusieurs personnes.

Terminal

curl -X POST https://api.vidoum.com/v1/playback-tokens \
  -H "Authorization: Bearer $VIDOUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "videoId": "8f2c…", "viewer": "sara.m@lycee.ma", "viewerRef": "u_7f3a91", "ttlSeconds": 14400 }'

→ { "embedUrl": "https://video.vidoum.com/embed/8f2c…?t=…", "hlsUrl": "…", "sessionId": "…", "expiresAt": … }

Champ	Rôle
`videoId`	La vidéo, qui doit être prête (statut ready)
`viewer`	Texte du filigrane, 64 caractères au plus : en général l’e-mail ou l’identifiant de l’apprenant
`viewerRef`	Facultatif : votre référence opaque de l’apprenant (lettres, chiffres, . _ : -, 128 caractères au plus ; pas d’e-mail). Elle revient avec la progression
`ttlSeconds`	Durée de validité : de 60 secondes à 12 heures, 4 heures par défaut

Le texte du filigrane est placé dans le lien signé et n’est enregistré nulle part chez Vidoum. Pour couper un accès avant l’expiration (abonnement résilié, partage constaté) : POST /v1/playback-sessions/{sessionId}/revoke. La révocation prend effet en 2 minutes environ.

Afficher le lecteur

HTML

<iframe
  src="EMBED_URL"
  title="Séance 3 — La cellule"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen
  referrerpolicy="no-referrer"
  style="width:100%;aspect-ratio:16/9;border:0"
></iframe>

Ajoutez &start=120 à l’URL pour reprendre à 2 minutes. Le lecteur propose la vitesse (0,5× à 2×), le choix de la qualité, le plein écran, les sous-titres et les raccourcis clavier. Pour que seuls vos sites puissent intégrer le lecteur, communiquez-nous leurs origines.

Événements de lecture

Le lecteur envoie à votre page des messages postMessage de la forme { source: "vidoum-player", type, seconds, duration, code? }.

type	Quand
`ready`	Le lecteur est prêt
`play`	Lecture lancée
`pause`	Lecture en pause
`timeupdate`	Position de lecture, une fois par seconde au plus
`ended`	Fin de la vidéo
`error`	Erreur ; code vaut expired (demandez un nouveau lien), network, media ou unsupported

JavaScript · page de cours

const playerOrigin = new URL(embedUrl).origin;
window.addEventListener("message", (event) => {
  if (event.origin !== playerOrigin) return; // toujours vérifier l’origine
  const msg = event.data;
  if (msg?.source !== "vidoum-player") return;
  if (msg.type === "timeupdate") saveProgress(msg.seconds, msg.duration);
  if (msg.type === "error" && msg.code === "expired") refreshLink();
});

Avec vidoum.js

Ce petit script crée l’iframe, vérifie l’origine des messages pour vous et ajoute des commandes.

HTML et JavaScript

<div id="lesson-video"></div>
<script src="https://video.vidoum.com/vidoum.js"></script>
<script>
  const player = Vidoum.embed("#lesson-video", { url: embedUrl, start: 120 });
  player.on("timeupdate", (e) => saveProgress(e.seconds, e.duration));
  player.on("error", (e) => { if (e.code === "expired") refreshLink(); });
  // player.play(), pause(), seek(30), setPlaybackRate(1.5), mute(), unmute(), destroy()
</script>

Suivre la progression

Votre plateforme reste la référence pour la progression, les règles d’achèvement et les certificats. Vidoum vous donne deux sources, à combiner selon vos besoins.

Côté serveur (recommandé). Le lecteur transmet à Vidoum, toutes les 10 secondes et à chaque pause, les passages réellement lus. Votre serveur lit le résultat avec le sessionId reçu avec le lien, ou reçoit le webhook playback.completed quand 90 % de la vidéo ont été vus.

Terminal

curl https://api.vidoum.com/v1/playback-sessions/SESSION_ID   -H "Authorization: Bearer $VIDOUM_API_KEY"

→ { "session": { "id": "…", "videoId": "…", "externalRef": "lesson:42", "viewerRef": "u_7f3a91",
     "progress": { "lastPosition": 312.4, "watchedSeconds": 305.1, "coveragePercent": 54, "completed": false, … } } }

Champ	Signification
`lastPosition`	Point de reprise (secondes)
`coveragePercent`	Part de la vidéo lue au moins une fois, de 0 à 100 ; revoir un passage ne l’augmente pas
`watchedSeconds`	Temps de lecture, borné par le temps réel (vitesse 2× au plus)
`completed`	Vrai dès que coveragePercent atteint 90

Pour une synchronisation par lots, GET /v1/playback-sessions?activeSince=… liste les sessions actives depuis votre dernier passage (filtres videoId, viewerRef, completed, pagination par curseur).

Côté page. Les événements postMessage ci-dessus permettent d’enregistrer la position vous-même : toutes les 15 secondes au plus, ainsi qu’aux événements pause et ended.

Une mesure indicativeCes chiffres viennent du navigateur de l’apprenant. Vidoum les borne (durée réelle de la vidéo, temps écoulé), mais un utilisateur déterminé peut les falsifier : ils conviennent pour reprendre une vidéo et suivre l’assiduité, pas pour délivrer seuls un certificat. Ils ne servent jamais à la facturation.