Guide d'intégration du lecteur Freecaster

Bienvenue ! Ce guide vous montre comment intégrer le lecteur vidéo Freecaster sur votre site web et le personnaliser en utilisant du HTML et du JavaScript simples.

Public cible

Cette documentation est destinée aux développeurs front-end familiers avec HTML, CSS et JavaScript.

Statistiques & conformité RGPD

Attention ! Par défaut, le lecteur ne collecte aucune statistique. Pour activer les modules de statistiques (comme Google Analytics, Mux, Youbora, etc.), vous devez définir l'attribut stats sur true (voir configuration). N'oubliez pas que l'obtention du consentement de l'utilisateur est obligatoire selon le RGPD.
Vous trouverez ici les meilleures pratiques d'intégration.

Premiers pas : intégrer le lecteur

Il existe deux manières d'intégrer le lecteur. Nous recommandons la méthode d'intégration JavaScript, car elle permet un accès plus facile à l'API du lecteur et offre plus de flexibilité pour personnaliser le style avec du CSS.

Intégration JavaScript (recommandée)Intégration Iframe

Inclure le script du lecteur : Ajoutez cette balise <script> à votre page (idéalement dans le <head> ou juste avant la balise de fermeture </body>). Vous n'en avez besoin qu'une seule fois, même pour plusieurs lecteurs.
```
<script async src="https://player.freecaster.com/freecaster/stable/fcplayer.js"></script>
```

Ajouter l'emplacement (placeholder) du lecteur : Insérez un <div> là où vous voulez afficher le lecteur. Utilisez la classe freecaster-player et l'attribut data-video-id avec l'ID de votre vidéo. Le script remplacera automatiquement ce div par le lecteur.

<!-- Exemple basique -->
<div class="freecaster-player" data-video-id="YOUR_VIDEO_ID"></div>

<!-- Exemple avec personnalisations -->
<div class="freecaster-player" 
     data-video-id="YOUR_VIDEO_ID" 
     data-width="640" 
     data-autoplay="true" 
     data-muted="true" 
     data-lang="fr-be" 
     data-stats="true">
</div>

Intégrez une <iframe> en utilisant cette structure d'URL : https://player.freecaster.com/embed/VIDEO_ID.html. Ajoutez les options de configuration en tant que paramètres de requête.

<!-- Conteneur iframe responsive -->
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
    <iframe 
        src="https://player.freecaster.com/embed/YOUR_VIDEO_ID.html?width=640&autoplay=true&muted=true&stats=true&lang=fr-be" 
        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;" 
        frameborder="0" 
        scrolling="no" 
        allowfullscreen>
    </iframe>
</div>

Remarque : le conteneur div est une méthode courante pour rendre l'iframe responsive (format 16:9). Ajustez padding-bottom pour d'autres formats.

Environnement de test

Lors de tests dans notre environnement de validation, utilisez player.freecaster-uat.com au lieu de player.freecaster.com dans les URLs.

Configuration HTML essentielle

Pour que le lecteur fonctionne correctement, notamment en ce qui concerne le responsive et l'affichage des caractères spéciaux, assurez-vous que ces balises <meta> sont présentes dans le <head> de votre document HTML :

<head>
  <meta charset="UTF-8"> 
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- Autres éléments du head -->
</head>

charset="UTF-8" : évite les problèmes d'encodage (caractères étranges).
viewport : garantit que le lecteur se redimensionne correctement sur différents appareils.

Configuration du lecteur

Vous pouvez personnaliser le comportement et l'apparence du lecteur avec des attributs.

Intégration JavaScript : utilisez des attributs data-* sur la balise <div> (par exemple data-autoplay="true").
Intégration Iframe : ajoutez des paramètres de requête à l'URL de l'iframe (par exemple ?autoplay=true).

Convention de nommage des attributs

Pour les paramètres d'URL de l'iframe, utilisez le camelCase plutôt que des tirets.

JS Embed : data-my-attribute="value"
Iframe Embed : ?myAttribute=value

Voici les options de configuration disponibles :

Attribute (`data-*`) / Parameter (`?param=`)	Valeur attendue	Défaut	Description
`audio_only`	boolean	`false`	Masque les éléments d'interface spécifiques à la vidéo pour une expérience axée sur l'audio. Voir la note ci-dessous.
`autopause`	boolean	`true`	Met automatiquement la vidéo en pause lorsqu'elle sort du champ de vision (viewport).
`autoplay`	boolean	`false`	Démarre la lecture automatiquement. Nécessite `muted=true` dans la plupart des navigateurs modernes. Voir la politique de lecture automatique de Google.
`cast`	boolean	`false`	Active les boutons Chromecast / AirPlay.
`chapters.enabled` / `chaptersEnabled`	boolean	`false`	Active la fonctionnalité de chapitres.
`chapters.list` / `chaptersList`	`[]<Chapter>` (JSON)	`[]`	Fournit les données des chapitres. Voir la note ci-dessous pour le format.
`chapters.style` / `chaptersStyle`	`hidden`, `dot`, `full_width`	`hidden`	Apparence des marqueurs de chapitres sur la barre de progression.
`controls`	boolean	`true`	Affiche ou masque la barre de contrôle du lecteur.
`float_on_scroll` / `floatOnScroll`	boolean	`false`	Affiche un mini-lecteur (Picture-in-Picture) qui reste visible quand le lecteur principal sort du champ de vision.
`height`	number		Définit la hauteur du lecteur en pixels (ex. `360`). Utilisez `100%` avec `width="100%"` pour le mode `stretching`.
`lang`	`language-country`		Définit la langue de l'interface du lecteur (ex. `en-us`, `fr-be`). Suit la norme RFC 5646.
`loop`	boolean	`false`	Recommence automatiquement la vidéo quand elle finit.
`multiplay`	boolean	`false`	Indique si ce lecteur doit continuer la lecture lorsqu’un autre lecteur sur la même page démarre la lecture. Utile pour les pages avec plusieurs lecteurs.
`muted`	boolean	`false`	Coupe le son par défaut. Requis pour que l'autoplay fonctionne de façon fiable.
`noads`	boolean	`false`	Désactive la publicité.
`poster`	URL d'image (string)		Spécifie l'URL d'une image de couverture affichée avant la lecture.
`preload`	`auto`, `metadata`, `none`	`auto`	Définit comment la vidéo doit être chargée : `auto` (charge les données vidéo), `metadata` (charge uniquement les dimensions, durée, etc.), `none` (pas de préchargement). Voir la section Instances multiples.
`speed.labels` / `speedLabels`	string		Libellés personnalisés pour les options de vitesse, séparés par des virgules (ex. `"Lent,Normal,Rapide"`). Doit correspondre au nombre d'options dans `speed.options`.
`speed.options` / `speedOptions`	string	`"0.2,0.5,1,2,10"`	Vitesse de lecture, séparés par des virgules (ex. `"0.5,1,1.5,2"`).
`stats`	boolean	`false`	Crucial : Active toute la collecte de statistiques (Google Analytics, Mux, Youbora, etc.). Nécessite le consentement utilisateur (RGPD).
`stretching`	`fill`, `cover`, `none`	`none`	Mode de redimensionnement de la vidéo et de l'image de couverture pour s'adapter aux dimensions du lecteur. Nécessite `width="100%"` et `height="100%"`. `fill` : étire sans respecter le ratio. `cover` : zoome/recadre pour remplir tout en conservant le ratio. `none` : taille d'origine (peut afficher des barres noires).
`subtitles.default_lang` / `subtitlesDefaultLang`	`lang` (ISO 639-1)		Définit la langue des sous-titres active par défaut via son code à 2 lettres (ex. `en`, `fr`).
`subtitles.lang` / `subtitlesLang`	`lang` (ISO 639-1)		Filtre le menu des sous-titres pour n'afficher que la langue spécifiée (ex. `es`).
`subtitles.native` / `subtitlesNative`	boolean	`false`	Utilise le rendu de sous-titres natif du navigateur (supporte le style VTT).
`thumbnails.src` / `thumbnailsSrc`	URL thumbnails		URL des miniatures de prévisualisation de la barre de progression (format VTT).
`trackers.ga.enabled` / `trackersGaEnabled`	boolean	`false`	Active spécifiquement la collecte de données Google Analytics 4 (GA4). Nécessite `stats=true`. Les événements sont envoyés au `window.dataLayer`.
`trackers.ga.tag_ids` / `trackersGaTagIds`	string		Liste de GA4 Measurement IDs séparés par des virgules (ex. `"G-XXXXXXXXXX,G-YYYYYYYYYY"`) vers lesquels envoyer les événements.
`volume`	number (0.0 à 1.0)	`1`	Définit le volume initial (0 = muet, 1 = volume maximal). Si l’utilisateur coupe le son manuellement, ce choix est conservé lors des chargements suivants. Les politiques de lecture automatique du navigateur peuvent influencer ce paramètre.
`watermark.enabled` / `watermarkEnabled`	boolean	`false`	Affiche ou masque l'image en surimpression (watermark).
`width`	number		Définit la largeur du lecteur en pixels (ex. `640`). Utilisez `100%` avec `height="100%"` pour le mode `stretching`.

Notes

dnt Obsolète

L'ancien attribut dnt est obsolète. Merci d'utiliser stats pour plus de clarté. dnt est conservé pour des raisons de rétrocompatibilité.

Utilisation de audio_only

Si vous intégrez du contenu audio et ne souhaitez pas afficher d'image d'affiche, réglez audio_only sur true pour une UI minimale.

Format de la liste de chapitres (chapters.list)

Fournissez un tableau JSON d'objets chapitre :

[
  {
    "id": "chapter-1-unique-id", 
    "start": 0,         // Temps de début en millisecondes
    "end": 15000,       // Temps de fin en millisecondes
    "title": "Introduction",
    "description": "Vue d'ensemble du sujet",
    "customData": { "key": "value" } // Optionnel : vos données personnalisées
  },
  {
    "id": "chapter-2-unique-id",
    "start": 15000,
    "end": 45000,
    "title": "Exploration approfondie" 
  }
]

start et end sont exprimés en millisecondes.
customData est transmis tel quel dans les événements liés aux chapitres.

Événements de chapitres

Lors de l'utilisation des chapitres, le lecteur émet des événements auxquels vous pouvez vous abonner (voir API d'instance du lecteur et Événements) :

fc_chapter_user_enter : l'utilisateur entre dans la plage d'un chapitre.
fc_chapter_user_leave : l'utilisateur quitte la plage d'un chapitre.

fc_chapter_user_mark : déclenché au moment précis du début de chaque chapitre.

Exemple d'utilisation de l'API du lecteur :

playerInstance.on('fc_chapter_user_enter', (payload) => {
  console.log(`Entré dans le chapitre : ${payload.data.title}`);
  console.log('Données personnalisées :', payload.data.customData); 
});

Accéder aux instances du lecteur

Utilisation de window.fcplayer

Vous pouvez utiliser la fonction globale window.fcplayer() pour obtenir des références aux instances fcplayer actives dans votre application.

Fonctionnement :

Le comportement de la fonction dépend de l'argument fourni :

Récupérer la première instance : Si vous appelez la fonction sans argument (window.fcplayer()), elle renverra la toute première instance fcplayer créée sur la page. Si aucun lecteur n'existe encore, elle retourne null.
Récupérer par ID : Si vous passez une string représentant l'identifiant unique d'un lecteur (window.fcplayer('mySpecificPlayerId')), la fonction recherchera l'instance associée à cet ID. Si elle est trouvée, elle renvoie cette instance spécifique. Si aucun lecteur avec cet ID n'existe, elle retourne null.

Paramètres :

playerId (String | undefined) :
- Optionnel. L'ID de l'instance du lecteur que vous voulez cibler.
- Si omis, la fonction récupère la première instance disponible.

Retour :

Une instance fcplayer (objet) si une correspondance est trouvée (ou si vous récupérez la première instance et qu'elle existe).
null si aucune instance n'existe ou si l'ID playerId spécifié ne correspond à aucun lecteur actif.

Exemples d'utilisation :

// Scénario 1 : Un seul lecteur attendu, ou besoin du lecteur par défaut
const player = window.fcplayer();
if (player) {
  // Interagir avec l'API du lecteur
  console.log('Lecteur trouvé :', player.id);
} else {
  console.error('Aucune instance fcplayer trouvée !');
}

// Scénario 2 : Contrôler un lecteur spécifique parmi plusieurs
const bannerPlayer = window.fcplayer('promo-video-player');
if (bannerPlayer) {
  bannerPlayer.mute();
} else {
  console.log('Le lecteur promo n\'est pas prêt ou n\'existe pas.');
}

Utilisation du callback Player

Le tableau window._fcpr fournit un mécanisme pour exécuter votre code dès qu'une instance fcplayer est initialisée. Vous pouvez "pusher" des fonctions de rappel (callbacks) dans ce tableau.

Mise en place :

Tout d'abord, assurez-vous que le tableau est initialisé, de préférence au début de l'exécution de votre page :

window._fcpr = window._fcpr || [];

Utilisation :

Poussez une fonction qui accepte l'instance du lecteur comme argument. Cette fonction s'exécutera pour toutes les instances existantes et pour toutes les futures instances au moment de leur création.

window._fcpr.push(playerInstance => {
  // Code à exécuter pour chaque instance du lecteur
  console.log('Lecteur détecté :', playerInstance.id);
  // Exemple : attacher un event listener
  playerInstance.on('error', (err) => {
    console.error(`Le lecteur ${playerInstance.id} a rencontré une erreur :`, err);
  });
});

Exemple : Lecture automatique (autoplay) lorsque visible

Ceci montre comment lancer automatiquement la lecture d'une vidéo via l'événement viewenter, qui n'est déclenché qu'une seule fois par lecteur.

Exemple :

// Ajouter ce script une seule fois sur la page
window._fcpr = window._fcpr || [];
window._fcpr.push(playerInstance => {
  // Lancer la lecture uniquement lorsque la première visibilité est détectée
  playerInstance.once('viewenter', () => {
    // Utilisez togglePlay(true) ou play() - togglePlay évite les erreurs si déjà en lecture
    playerInstance.togglePlay(true); 
    console.log(`Le lecteur ${playerInstance.id || ''} est entré en vue et a démarré la lecture.`);
  });
});

Vous pouvez créer des liens qui démarrent (et éventuellement arrêtent) la lecture de la vidéo à des moments précis en utilisant les paramètres de requête start_time et end_time. Les valeurs sont exprimées en secondes.

Exemple : https://player.freecaster.com/embed/VIDEO_ID.html?start_time=120&end_time=300

Ce lien démarrera la vidéo à 2 minutes (120s) et la mettra automatiquement en pause à 5 minutes (300s).

Limitation

Cette fonctionnalité ne fonctionne que pour la Vidéo à la Demande (VOD), pas pour les flux en direct (live).

Obtenir le temps actuel

Vous pouvez obtenir le temps de lecture actuel en secondes via l'API du lecteur : playerInstance.currentTime.

API d'instance du lecteur (JavaScript Embed uniquement)

Pour contrôler le lecteur de manière programmatique (play, pause, seek, écoute d'événements, etc.), vous avez besoin de son instance. L'instance n'est disponible qu'avec l'intégration JavaScript.

Limitation iframe

Vous ne pouvez pas accéder directement à l'instance du lecteur ni à son API avec une intégration iframe.

Voici comment obtenir l'instance du lecteur :

Par l'ID de l'élément : Attribuez un id unique au <div> de votre lecteur.

<div id="my-player" class="freecaster-player" data-video-id="VIDEO_ID"></div>

Ensuite, utilisez la fonction globale fcplayer() :

// Attendre que le script du lecteur soit chargé et initialise le lecteur
// Un moyen simple est d'attendre l'événement DOMContentLoaded ou d'utiliser le callback ci-dessous
document.addEventListener('DOMContentLoaded', () => {
  const playerInstance = fcplayer('my-player');
  if (playerInstance) {
    // Vous pouvez maintenant utiliser l'instance
    playerInstance.play(); 
  }
});

En utilisant le callback window._fcpr : Ce tableau reçoit une fonction de rappel pour chaque instance de lecteur créée sur la page. C'est utile si vous ne connaissez pas l'ID à l'avance ou si vous voulez gérer plusieurs lecteurs.

window._fcpr = window._fcpr || []; // Initialiser s'il n'existe pas

window._fcpr.push((playerInstance) => {
  console.log(`Lecteur prêt : ${playerInstance.id || 'Pas d\'ID'}`);

  // Exemple : attacher un event listener à un lecteur spécifique
  if (playerInstance.id === 'my-special-player') {
    playerInstance.on('play', () => console.log('Le lecteur spécial a démarré !'));
  }

  // Exemple : attacher un écouteur à TOUS les lecteurs
  playerInstance.on('error', (err) => console.error(`Erreur lecteur :`, err));
});

Récupérer toutes les instances : Vous pouvez obtenir un tableau de toutes les instances initialisées à tout moment avec :

const allPlayers = window.fcplayers();

Gérer plusieurs lecteurs sur une page

Si vous avez plusieurs lecteurs visibles simultanément, le comportement par défaut des navigateurs (notamment avec preload="auto" ou autoplay="true") peut entraîner une consommation excessive de bande passante et des problèmes de performance, car plusieurs vidéos peuvent tenter de se charger en même temps.

Recommandations :

Définissez preload="none" et autoplay="false" sur vos balises div de lecteur.
Utilisez l'API du lecteur pour démarrer la lecture uniquement lorsque le lecteur entre dans le champ de vision (viewport).
Vérifiez si data-multiplay n'est pas réglé sur true, ce qui empêche la mise en pause automatique des autres lecteurs lorsque l'un d'eux démarre.

Exemple d'implémentation :

<!-- Lecteur 1 -->
<div class="freecaster-player"
     data-video-id="VIDEO_ID_1"
     data-multiplay="false"       // Vous pouvez aussi ignorer ce champ s'il doit rester `false`
     data-preload="none"
     data-muted="true" 
     data-autoplay="false">
</div> 

<!-- Lecteur 2 -->
<div class="freecaster-player"
     data-video-id="VIDEO_ID_2"
     data-multiplay="false"
     data-preload="none"
     data-muted="true"
     data-autoplay="false">
</div>

// Ajouter ce script une seule fois sur la page
window._fcpr = window._fcpr || [];
window._fcpr.push(playerInstance => {
  // Démarrer la lecture uniquement à la première entrée en vue
  playerInstance.once('viewenter', () => {
    playerInstance.togglePlay(true); 
    console.log(`Le lecteur ${playerInstance.id || ''} est entré en vue et a démarré la lecture.`);
  });

  // Optionnel : mettre en pause quand il quitte la vue (si vous n'utilisez pas l'attribut autopause)
  // playerInstance.on('viewleave', () => {
  //   playerInstance.pause();
  //   console.log(`Le lecteur ${playerInstance.id || ''} a quitté la vue et a été mis en pause.`);
  // });
});

Cette approche fournit une expérience similaire à l'autoplay sans surcharger le navigateur au chargement.

Propriétés du lecteur (API)

Accédez à ces propriétés sur une instance de lecteur :

Propriété	Description	Exemple d'utilisation	Type de retour	Exemple de valeur de retour
`audioTracks`	Liste des pistes audio disponibles. Voir MDN	`player.audioTracks`	AudioTrackList	`AudioTrackList {length: 2, 0: AudioTrack, 1: AudioTrack}`
`blackBarsHeight`	Retourne la hauteur totale en pixels des bandes noires (si présentes) dues à un décalage entre les dimensions du conteneur et le ratio de la vidéo.	`player.blackBarsHeight`	number	`100` (si barres noires présentes) / `0` (si aucune barre)
`config`	L'objet de configuration actuel du lecteur.	`player.config`	object	`{ autoplay: false, muted: true, ... }`
`container`	L'élément principal `HTMLElement` contenant le lecteur.	`player.container`	HTMLElement	`<div class="freecaster-player...">`
`controlbar`	L'élément `HTMLElement` de la barre de contrôle du lecteur.	`player.controlbar`	HTMLElement	`<div class="fp-controls...">`
`currentAudioTrack`	La piste audio actuellement active/en cours de lecture, le cas échéant.	`player.currentAudioTrack`	AudioTrack \| null	`AudioTrack {id: 'en', kind: 'main', label: 'English', language: 'en'}` / `null`
`currentTime`	Position de lecture actuelle en secondes. Voir MDN	`player.currentTime`	number	`123.456`
`currentTimecode`	Position de lecture actuelle sous forme de chaîne de caractères formatée (HH:MM:SS:FF ou HH:MM:SS.ms).	`player.currentTimecode`	string	`"00:02:03:15"` ou `"00:02:03.500"`
`currentTimestamp`	Position de lecture actuelle sous forme de timestamp UTC en millisecondes (Live DASH/HLS uniquement, nécessite une configuration spécifique).	`player.currentTimestamp`	number \| null	`1678886400123`
`duration`	Durée totale de la vidéo en secondes. Retourne `Infinity` pour les flux en direct (live).	`player.duration`	number	`600.5` ou `Infinity`
`id`	L'attribut `id` de l'élément conteneur du lecteur, s'il est défini.	`player.id`	string \| null	`"my-player"`
`live`	Booléen indiquant si la source vidéo actuelle est un flux en direct (live).	`player.live`	boolean	`true` / `false`
`muted`	Booléen indiquant si le lecteur est actuellement en sourdine.	`player.muted`	boolean	`true` / `false`
`paused`	Booléen indiquant si le lecteur est actuellement en pause.	`player.paused`	boolean	`true` / `false`
`subtitlesEnabled`	Booléen indiquant si les sous-titres/légendes sont actuellement activés sur le lecteur.	`player.subtitlesEnabled`	boolean	`true` / `false`
`version`	La chaîne de caractères correspondant à la version du lecteur.	`player.version`	string	`"freecaster-player x.y.z (core v...)"`
`volume`	Niveau de volume actuel (0.0 à 1.0).	`player.volume`	number	`0.75`

Propriétés dépréciées

Ces attributs/propriétés sont anciens. Veuillez utiliser les alternatives listées dans le tableau de configuration principal.

Déprécié	Utiliser à la place
`mute`	`muted` (attribut)
`repeat`	`loop` (attribut)
`aspectratio`	Géré via CSS/conteneur
`playbackRateControls`	`speed.options` etc.
`localization`	`lang` (attribut)
`displaytitle`	(Pas d'équivalent direct)
`displaydescription`	(Pas d'équivalent direct)
`fc-token`	`data-video-id`
`locale`	`lang` (attribut)
`dnt`	`stats` (attribut)

Méthodes du lecteur (API)

Appelez ces méthodes sur une instance de lecteur :

Méthode	Description	Exemple d'utilisation
`play()`	Démarre ou reprend la lecture.	`player.play()`
`pause()`	Met la lecture en pause.	`player.pause()`
`togglePlay(force?)`	Bascule entre lecture et pause. Le booléen optionnel force l'état (`true` = lecture, `false` = pause).	`player.togglePlay()` `player.togglePlay(true)`
`seek(time)`	Saute à un temps spécifique (en secondes) ou à un timestamp (millisecondes, live/VOD avec décalage de départ).	`player.seek(120)` (aller à 2 min) `player.seek(1678886400123)` (aller à un timestamp, si applicable)
`setSrc(source)`	Charge une nouvelle source vidéo. Voir la note ci-dessous pour le format.	`player.setSrc('new_video.mp4')` `player.setSrc({ type: 'application/dash+xml', src: 'manifest.mpd' })`
`loadVideo(videoId)`	Charge une nouvelle vidéo via son ID Freecaster, en remplaçant la vidéo actuelle.	`player.loadVideo('NEW_VIDEO_ID')`
`destroy()`	Supprime l'instance du lecteur et ses éléments DOM associés. Nettoie les écouteurs d'événements.	`player.destroy()`
`toggleFullScreen()`	Active ou quitte le mode plein écran.	`player.toggleFullScreen()`
`setConfig(key, value)`	Met à jour une ou plusieurs options de configuration après l'initialisation.	`player.setConfig('volume', 0.5)` `player.setConfig({ controls: false, loop: true })`
`goBackToLive()`	Pour les flux en direct avec DVR, revient au direct (live edge).	`player.goBackToLive()`
`mute(shouldMute)`	Coupe (`true`) ou réactive (`false`) le son du lecteur.	`player.mute(true)`
`setVolume(level)`	Définit le volume (0.0 à 1.0).	`player.setVolume(0.8)`
`on(event, callback)`	Attache un event listener.	`player.on('play', () => console.log('Playback started'))`
`off(event, callback)`	Supprime un event listener.	`player.off('play', myPlayHandler)`
`once(event, callback)`	Attache un event listener qui ne s'exécute qu'une seule fois.	`player.once('ended', () => console.log('Video finished'))`

seek() avec timestamps

L'utilisation d'un timestamp absolu (millisecondes) avec seek() nécessite :

Live : Le timestamp doit se trouver dans la fenêtre DVR disponible.
VOD : La propriété player.config.start (généralement fournie par l'API) doit être disponible pour que le lecteur puisse faire correspondre le timestamp à un décalage vidéo.

Format pour setSrc()

Le paramètre source pour setSrc() peut être :

Une simple chaîne d'URL : 'https://path/to/video.mp4'
Un objet source : { type: 'application/dash+xml', src: 'https://path/to/manifest.mpd' }
Un tableau d'objets source (le lecteur choisit le premier compatible) :

[
  { type: 'application/x-mpegurl', src: 'https://path/to/playlist.m3u8' },
  { type: 'video/mp4', src: 'https://path/to/fallback.mp4' }
]

Intégration de Google Analytics (GA4)

Pour envoyer les événements du lecteur vers Google Analytics 4 :

Inclure la balise Google GA : Assurez-vous que la balise Google standard gtag.js est présent sur votre page. (Documentations Google)
Activer les statistiques : Définissez l'attribut data-stats="true" sur votre div de lecteur.
Activer le tracker GA : Définissez data-trackers.ga.enabled="true".
(Optionnel) Spécifier les IDs de tag : Si nécessaire, fournissez votre ou vos ID(s) de mesure GA4 via data-trackers.ga.tag_ids="G-XXXXXXXXXX,G-YYYYYYYYYY". Si omis, les événements peuvent être envoyés aux tags configurés globalement via gtag('config', 'GA_MEASUREMENT_ID').

<!-- Assurez-vous que le script GA est chargé sur la page -->

<div class="freecaster-player" 
     data-video-id="YOUR_VIDEO_ID"
     data-stats="true"  
     data-trackers.ga.enabled="true" 
     data-trackers.ga.tag_ids="G-XXXXXXXXXX"> 
</div>

Les événements du lecteur (comme play, pause, seek, ended, error, etc.) seront automatiquement envoyés au window.dataLayer.

Événements

Vous pouvez écouter divers événements sur l'instance du lecteur avec player.on('eventName', callback).

Événements médias HTML standard

Ces événements sont basés sur la spécification HTML5 pour l'élément vidéo.

Événement	Description
`play`	Déclenché lorsque la lecture commence ou reprend.
`pause`	Déclenché lorsque la lecture est mise en pause.
`ended`	Déclenché lorsque la lecture atteint la fin du média.
`error`	Déclenché lorsqu'une erreur survient lors du chargement ou de la lecture.
`seeking`	Déclenché lorsqu'une opération de recherche (seek) démarre.
`seeked`	Déclenché lorsque l'opération de recherche se termine.
`timeupdate`	Déclenché fréquemment pendant la progression du `currentTime`. (Utiliser avec parcimonie pour les performances).
`volumechange`	Déclenché lorsqu'il y a un changement de volume ou de l'état "muet".
`ratechange`	Déclenché lorsque la vitesse de lecture change.
`waiting`	Déclenché lorsque la lecture s'arrête en raison de la mise en mémoire tampon (buffering).
`playing`	Déclenché lorsque la lecture reprend après une mise en mémoire tampon ou une recherche.
`loadstart`	Déclenché lorsque le navigateur commence à rechercher des données média.
`loadedmetadata`	Déclenché lorsque les métadonnées du média (durée, dimensions) sont chargées.
`loadeddata`	Déclenché lorsque la première image de données est disponible.
`canplay`	Déclenché lorsque le lecteur peut commencer la lecture, bien qu'il puisse encore avoir besoin de charger des données.
`canplaythrough`	Déclenché lorsque le lecteur estime pouvoir lire le média jusqu'à la fin sans interruption.
`resize`	Déclenché lorsque les dimensions du lecteur changent.

Événements personnalisés Freecaster

Ces événements sont spécifiques au lecteur Freecaster.

Événement	Description	Exemple de payload
`fullscreenenter`	Déclenché lorsque le lecteur passe en mode plein écran.	-
`fullscreenexit`	Déclenché lorsque le lecteur quitte le mode plein écran.	-
`viewenter`	Déclenché lorsque l'élément du lecteur devient visible dans le champ de vision (viewport) du navigateur.	-
`viewleave`	Déclenché lorsque l'élément du lecteur sort du champ de vision du navigateur.	-
`fcplayerDestroy`	Déclenché juste avant la suppression complète de l'instance du lecteur.	-
`fcplayerSrcChanged`	Déclenché après le changement réussi de la source vidéo via `setSrc` ou `loadVideo`.	`{ src: 'nouvelle_url_ou_objet_source' }`
`fcplayerConfigChanged`	Déclenché après la mise à jour de la configuration via `setConfig`.	`{ key: 'clé_config', value: 'nouvelle_valeur' }` ou `{ changes: { clé1: valeur1, ... } }`
`fc_chapter_user_enter`	Déclenché lors de l'entrée dans la plage temporelle d'un chapitre (défini dans `chapters.list`).	`{ data: ObjetChapitre }`
`fc_chapter_user_leave`	Déclenché lors de la sortie de la plage temporelle d'un chapitre.	`{ data: ObjetChapitre }`
`fc_chapter_user_mark`	Déclenché exactement au moment du `start` de chaque chapitre lors de la lecture.	`{ data: ObjetChapitre }`
`fcplayerCountdownTick`	(Si applicable) Déclenché chaque seconde pendant un compte à rebours pré-roll.	`{ remaining: nombre }` (secondes)
`fcplayerCountdownEnabled`	(Si applicable) Déclenché lorsqu'un compte à rebours démarre.	-
`fcplayerCountdownDisabled`	(Si applicable) Déclenché lorsqu'un compte à rebours est arrêté ou se termine naturellement.	-
`fcplayerCountdownZero`	(Si applicable) Déclenché lorsque le compte à rebours atteint zéro.	-

Exemple d'écouteur :

playerInstance.on('viewenter', () => {
  console.log('Le lecteur est maintenant visible !');
});

playerInstance.on('fcplayerSrcChanged', (payload) => {
  console.log('Nouvelle source chargée :', payload.src);
});

playerInstance.on('fc_chapter_user_enter', (payload) => {
  console.log(`Entrée dans le chapitre : ${payload.data.title}`);
});

Mode Audio uniquement

Le lecteur Freecaster peut être configuré pour fonctionner en mode audio uniquement, ce qui le rend idéal pour les podcasts, les morceaux de musique ou la lecture de fichiers MP3.

Comment l'activer

Définissez l'attribut audio_only sur true :

<!-- Intégration JavaScript -->
<div class="freecaster-player" 
     data-video-id="VOTRE_ID_AUDIO" 
     data-audio_only="true"
     data-poster="couverture.jpg"
     data-title="Nom de l'artiste"
     data-description="Titre de la piste">
</div>

Comportement en mode Audio uniquement

L'interface (skin) du lecteur bascule vers une mise en page adaptée à l'audio.
Si une image de couverture (poster) est définie, elle apparaît au-dessus de la barre de progression (à la manière d'une pochette d'album).
Le titre de la vidéo est affiché comme étant l'Artiste.
La description de la vidéo est affichée comme étant le Titre de la piste.

Définition des attributs

L'Artiste, le Titre de la piste et l'Affiche peuvent être définis soit via les attributs data-*, soit via les paramètres de requête (iframe), ou encore être récupérés depuis les métadonnées de la vidéo sur le backend. Si les deux sont définis, les valeurs transmises par attributs ou via l'iframe l'emportent sur celles du backend.

Support des transcriptions

Un fichier de transcription peut être uploadé côté backend pour un asset audio ou vidéo. Lorsqu'il est disponible, la transcription apparaîtra automatiquement dans le lecteur.

Le lecteur Freecaster utilise des cookies et le stockage local HTML (local storage) pour des fonctionnalités nécessaires et, si activé, pour les statistiques. Les services tiers intégrés (comme Youbora) utilisent également ces technologies.

Qu'est-ce que les cookies et le stockage local ?

Cookies : Petits fichiers stockés par le navigateur, souvent utilisés pour la gestion de session ou des préférences.
Stockage local (local storage) : Mécanisme de stockage web permettant de conserver des données de manière persistante dans le navigateur.

Désactiver le stockage non essentiel

Vous pouvez empêcher le lecteur de créer des cookies et des éléments de stockage local liés aux statistiques en définissant l'attribut stats sur false :

<div class="freecaster-player" data-video-id="VOTRE_ID_VIDEO" data-stats="false"></div>

Cela désactivera la collecte de statistiques, mais pourra réduire notre capacité à analyser les performances et les incidents du lecteur. Le stockage fonctionnel essentiel (comme to) restera utilisé.

Éléments de stockage utilisés

Freecaster (Fonctionnalités nécessaires)

Nom	Stockage	But	Expiration
`to`	Stockage local	Stocke les données de calcul du décalage temporel nécessaires pour afficher correctement les comptes à rebours des événements en direct (live).	30 minutes

Youbora (Statistiques - Uniquement si `stats=true`)

Nom	Stockage	But	Expiration
`youbora.accCode`	Stockage local	Stocke le code de compte Youbora.	Permanent
`youbora.data`	Stockage local	Met en cache les paramètres de l'API Youbora.	Permanent
`youbora.dataTime`	Stockage local	Horodatage (timestamp) des paramètres mis en cache.	Permanent
`youbora.host`	Stockage local	Point de terminaison (endpoint) hôte pour envoyer les statistiques Youbora.	Permanent
`youbora.offlineViews`	Stockage local	Stocke les pings analytiques non envoyés (en cas de mode hors ligne).	Permanent
`youbora.session`	Stockage local	Identifiant unique pour la session de visionnage actuelle.	Permanent
`youbora.sessionExpire`	Stockage local	Horodatage d'expiration de l'identifiant de session.	Permanent
`youbora.youboraDeviceUUID`	Stockage local	Identifiant unique d'appareil généré de manière aléatoire pour la collecte de données.	Permanent

(Remarque : "Permanent" signifie que les données persistent jusqu'à ce qu'elles soient supprimées manuellement par l'utilisateur ou par le site web.)

Pour être conforme au RGPD, la collecte des statistiques du lecteur ne doit être activée qu'après avoir obtenu le consentement explicite de l'utilisateur.

Workflow recommandé :

Recueillir le consentement : Avant d'initialiser le lecteur avec les statistiques activées, affichez une interface de consentement (ex: bannière, popup) à l'utilisateur.
Gérer le choix de l'utilisateur :
- Consentement donné : Enregistrez le consentement (par ex. en définissant data-stats="true" sur l'élément conteneur du lecteur).
- Consentement refusé / Pas encore de choix : Laissez l'élément conteneur du lecteur tel quel (n'ajoutez pas data-stats="true").
Initialiser le lecteur : Insérez la balise <div class="freecaster-player"></div> dans le document, fcplayer.js prendra le relais et chargera le lecteur vidéo.