Comment fonctionne la lecture

Pour lire un asset Videas dans votre propre page, vous ne diffusez pas depuis une URL fixe. Vous passez par un court flux en deux temps qui garde votre clé API secrète et ne transmet au navigateur que des URLs signées, à durée de vie courte. Cette page explique le modèle ; les deux suivantes montrent le code (SDK JavaScript et API REST).

Vous n’en avez peut-être pas besoin. Si tout ce qu’il vous faut, c’est la vidéo dans une page, chaque média Videas donne un code d’intégration — une balise script ou une iframe — à coller tel quel, qui embarque déjà le lecteur, ses chapitres et ses sous-titres. Ce guide s’adresse au cas où vous pilotez la lecture vous-même : votre propre player, une app mobile, un rendu côté serveur.

Les deux étapes

Émettre un jeton de player — appelez GET /videos/{uid}/player/ (ou /assets/{uid}/player/). Renvoie les métadonnées du player (config, thème, overlays, items) et un playback_token valide 4 heures.
Résoudre les URLs de flux — appelez POST /playback/info/ avec le playback_token et l’asset_id. Renvoie les URLs média signées, à durée limitée (hls_url, …) à fournir au player vidéo.

Cette séparation isole le jeton — sûr à exposer à un navigateur — de votre clé secrète, et fait que les vraies URLs média sont signées et expirent vite.

Le modèle de sécurité (à lire en premier)

Les deux endpoints s’authentifient différemment, et c’est le point le plus important à ne pas rater :

Étape	Endpoint	Auth	Où l’appeler
1. Émettre le jeton	`GET …/player/`	Clé API (`Authorization: Bearer sk_…`)	Serveur uniquement
2. Résoudre les URLs	`POST …/playback/info/`	`playback_token` (aucune clé API)	Le navigateur convient

Règle d’or. Votre clé sk_ est un secret — ne l’envoyez jamais à un navigateur ni à une app mobile. L’étape 1 doit tourner sur votre serveur. Le playback_token renvoyé, lui, est fait pour être transmis au navigateur, qui réalise l’étape 2 seul.

Architecture recommandée

┌─────────────┐  1. getPlayer(uid)   [clé sk_]     ┌──────────────┐
│ Votre       │ ──────────────────────────────────▶│  API Videas  │
│ serveur     │◀────────────────────────────────── │              │
│ (clé sk_)   │   playback_token (valide 4h)        └──────────────┘
└─────────────┘
      │
      │  2. transmettre playback_token + asset_id à la page
      ▼
┌─────────────┐  3. POST /playback/info/  [jeton]  ┌──────────────┐
│ Navigateur  │ ──────────────────────────────────▶│  API Videas  │
│ (player)    │◀────────────────────────────────── │              │
└─────────────┘   hls_url signée (courte durée)     └──────────────┘
      │
      │  4. fournir hls_url à hls.js / HLS natif
      ▼
   ▶ lecture

Votre serveur émet un jeton et peut le réutiliser pendant 4 heures ; le navigateur ré-résout les URLs signées dès qu’elles expirent (elles vivent bien moins longtemps que le jeton). Quand le jeton lui-même expire, émettez-en un nouveau côté serveur.

Ce que renvoie `playback/info/`

La réponse est typée par l’asset — le champ type indique la forme reçue. Chaque URL média est un objet { url, expires_at }.

Vidéo (type: "video")

Champ	Signification
`hls_url`	Manifeste HLS (`.m3u8`) — le flux principal (débit adaptatif, sous-titres & pistes audio intégrés)
`source_url`	MP4 progressif — repli hérité quand HLS est indisponible
`preview_sprites_url`	Planche de sprites pour les vignettes de la barre de progression
`chapters`	`[{ title, start_time, thumbnail_url }]`

Audio (type: "audio") : source, waveform_url, chapters, subtitle_tracks ([{ label, language, is_default, src }]).

Image (type: "image") : variants ([{ name, dimensions, url }]).

Document (type: "document") : url, thumbnails (par page).

Tiers (type: "third_party", ex. YouTube/Vimeo) : embed_url, provider, provider_id — intégrez l’iframe du fournisseur plutôt qu’un player HLS.

Champs présents sur tous les types

expires_at — quand ces infos de lecture (et leurs URLs signées) expirent ; ré-résolvez après cette date.
resume_position_seconds — la position sauvegardée du spectateur, s’il y en a une. Placez-vous ici pour reprendre là où il s’était arrêté (null s’il n’y a rien à reprendre).
blocked — voir ci-dessous.

Gérer l’état `blocked`

Quand le portefeuille de crédits du propriétaire de l’asset est vide, la lecture est suspendue : la réponse revient avec blocked: true et aucune URL média. Vérifiez-le toujours avant de câbler le player, et affichez un message neutre « temporairement indisponible » plutôt qu’un player cassé :

{ "type": "video", "blocked": true, "hls_url": null, "expires_at": "…" }

Durées de vie jeton & URLs — récapitulatif

playback_token → valide 4 heures. Émettez-le côté serveur ; réutilisez-le.
URLs média signées (hls_url, …) → courte durée (voir chaque expires_at). Rappelez POST /playback/info/ pour les rafraîchir — aucun nouveau jeton nécessaire tant que le jeton de 4 h n’a pas expiré.