DOCUMENTATION SUR L'AUDIO-VIDEO


Table des matières

Console audio-vidéo

Le lecteur audio-vidéo de Radio-Canada est un lecteur universel pour nos différents sites. Il est aussi à la disposition de nos partenaires afin de leur permettre de rendre accessibles des contenus audio-vidéo, de type « sur demande » ou « en direct » sur tous les fureteurs, incluant les fureteurs de téléphones intelligents et tablettes.

Les fonctionnalités du lecteur sont, pour la plupart, paramétrables et peuvent être activées ou désactivées au besoin. Une API publique permet aussi d’utiliser le lecteur avec le langage Javascript.


Mise en garde concernant l’utilisation du iframe

Vous devez éviter d’utiliser la console dans un iframe à cause des restrictions suivantes 

  • La fonctionnalité de plein écran n’est pas disponible sur IPad (le bouton est masqué).
  • Pour le mobile, la publicité ne jouera pas sur IOS et Android.


Compatibilité avec les navigateurs web et devices

Les navigateurs supportés, ainsi que les versions sont indiqués ici dans la section Navigateurs supportés sur desktop”.

Incompatibilités identifiées :

  • la console audio n’est pas compatible avec le navigateur IE11.0.
  • La vidéodescription ne fonctionne pas sur Nexus 7 et 5 pour l’OS version 4.4. Il faut mettre à jour l’OS avec une version plus récente (opérationnel à partir de Android 6.0).



Nouvelle console audio/vidéo

8 octobre 2020

La console audio/vidéo a fait peau neuve, une version améliorée est maintenant disponible. Voici comme l'intégrer.


Intégration de la console

Voici les étapes à suivre pour intégrer le lecteur audio-vidéo.

1- Chargement du script

Script JS

Utiliser l'une des URL suivantes: 

DEV: https://services.radio-canada.ca/media/player/js/dev?version=latest

PROD: https://services.radio-canada.ca/media/player/js/prod?version=latest

Le paramètre "version" permet de charger une version spécifique du lecteur, si non spécifiée, la plus récente version est chargée.


Package NPM

Se connecter au registre playerweb en suivant les instructions.

https://dev.azure.com/rcmn/www.radio-canada.ca/_packaging?_a=connect&feed=medianumerique%40Local

Définir le package playerjs-v2 sur le registre playerweb. Dans le fichier .npmrc du projet, ajouter la ligne suivante:

@cbcradcan:registry=https://pkgs.dev.azure.com/rcmn/_packaging/medianumerique/npm/registry/

Installer le package NPM @radcan/playerjs-v2

npm install @cbcradcan/playerjs-v2 --save-dev

Pendant l'installation, si des dépendances sont manquantes, elles seront affichés en warning.

Installer les dépendances du player

npm install axios@^0.18.0 bowser@^2.4.0 hls.js@^0.12.4 loadcss@0.0.2 loadjs@^3.6.1 lottie-web@5.5.9 moment@2.24.0 react-redux@^5.1.1 react-resize-observer@^1.1.1 redux@^4.0.1 svgxuse@^1.2.6 underscore@^1.9.1 --save

2- Définir un élément HTML où le lecteur sera situé.

Exemple d'élément:

<div id="video-element"></div>

Contient le lecteur, celui-ci sera en largeur 100% de l'élément parent. La taille du lecteur devrait être gérée à ce niveau. 


3- Définition des paramètres d'intégrations

Le lecteur supporte plusieurs paramètres d'intégration pour modifier son comportement. Vous trouverez tous les paramètres et leur fonction ici.

Par la suite on créer un objet JavaScript contenant les paramètres voulus, qui seront ensuite utilisés à l'initialisation du lecteur.

varparams = {
autoplay:false,
canReduce:true,
heartbeat:true,
clientId:'radiocanada_unit'
};


4- Initialisation du lecteur

Script JS

L'objet "RadioCanadaPlayer" contient la méthode "initPlayerJS".

Package NPM

Importer la méthode "initPlayerJS"

import'../node_modules/@cbcradcan/playerjs-v2/playerJsV2.css';
import {initPlayerJs} from'@cbcradcan/playerjs-v2';


La méthode "initPlayerJS" crée une instance du lecteur et accepte 3 arguments.

  • video-element-container-id: L’ID de l'élément créé à l'étape 2
  • idMedia: Le id du média désiré. (Le média peut-être changé par l'API utilisateur)
  • appCode: Le appCode du média précisé à l'étape précédente.
  • Les paramètres déclarés à l'étape 3


Script JS

varplayer = RadioCanadaPlayer.initPlayerJs([video-element-container-id], [idMedia], [appCode], [params]);

Package NPM

varplayer = initPlayerJs([video-element-container-id], [idMedia], [appCode], [params]);

Dans ce cas, l'instance du lecteur initialisé sera accessible par la variable "player" il sera donc possible d'utiliser l'API du lecteur en passant par cette variable.


Paramètres d'intégration


Nom du paramètre

Valeurs posible

Valeur par default

Environement disponible

Description

accessToken

string

null

DEV | PROD

Token d'identification de l'utilisateur pour permettre la lecture des médias premium. 

activateComscoreV2

true | false

false 

DEV | PROD

Active la métrie comscore v2.

adUrl

string <url>

null

DEV 

Force une URL où récupérer un VAST de publicité.

audioApi

true | false 

null

DEV | PROD

Mets le lecteur en mode audio API. Ce qui "render" seulement un tag audio sans aucun visuel. 

autoplay

true | false

false

DEV | PROD

Permets la lecture automatique du média

brandColor

string ex: "#00A5AD"

null

DEV | PROD

Permets d'assigner la couleur de marque au différents éléments du lecteur.

canReduce

true | false

false

DEV | PROD

Affiche le bouton reduce, qui permet de mettre le lecteur en mode réduit.

clientId

string ex: "radiocanadaca_unit"

null

DEV | PROD

Permet de récupérer les paramètres selon le clientId dans bambou.

disableInfoPanel

true | false

false

DEV | PROD

Cache le panneau d'information comprenant le titre, le nom de l'émission, le bouton retour et le bouton X.

disableInfoPanelButton

true | false

true

DEV | PROD

Cache la flèche en haut à gauche indiquant à l'intégration que l'utilisateur souhaite quitter le player

disableTracking

true | false

false

DEV | PROD

Désactive la metrie pour le lecteur audio/vidéo.

reduceOnInit

true | false

false 

DEV | PROD

Initialise le player en mode reduit.

removeUnreduce

true | false 

false

DEV | PROD

Retire le bouton unreduce de la console lorsqu'elle est en mode reduce.

dai

true | false

false 

DEV | PROD

Active les publicités DAI si disponibles.

disableShortcuts

true | false

false

DEV | PROD

Permets de désactiver les raccourcis claviers pour une instance du lecteur.

disableTimeControl

true | false

null

DEV | PROD

Contrôle l'affichage de l'heure dans la barre de contrôles pour les diffusions en direct.

servicesEnv

string ex:"dev"

null

DEV | PROD

Permets de spécifier un environement pour metaMedia et validationMedia à des fins de tests seulement. Il bypass les paramètres spécifiés dans le build du player.

heartbeat

true | false

false

DEV

Active la métrie Adobe HeartBeat

heartbeatDebug

true | false

false

DEV

Permet de mettre heartbeat en mode debug. Ce qui affiche plusieurs messages dans la console. 

mediaAnalyticsEnable

true | false 

false 

DEV

Active la métrie de média analytics.

noAds

true | false

false

DEV

Désactive les publicités sur cette instance du lecteur.

pageShare

string

null

DEV | PROD

URL vers la page web référente du partage. Si non défini, le bouton de partage ne s'affichera pas.
L'URL comprend les paramètres pouvant être utilisés dans la construction de l'URL sous forme: <%=PARAM%>

Par exemple, ici.radio-canada.ca aura comme pageShare:
http://ici.radio-canada.ca/info/videos/media-<%=idMedia%>/<%=urlDesc%>?isAutoPlay=true

Liste des paramètres:

  • appCode: Code d'application du média (medianet, medianetlive, toutv)

  • idMedia: Code numérique du média

  • title: Titre du média provenant des métas

  • urlDesc: Dernière partie de l'URL de la page en cours de consultation après le dernier "/" et avant le "?"

providerId

string <azure | hls | html>

html

DEV | PROD

Si présent, force le type de provider qui sera utilisé pour la lecture du média.

width

string

null

DEV | PROD

Force la largeur du lecteur.

exitFullscreenOnEnd

true | false

true

DEV | PROD

Permet de choisir le comportement de player à la fin de lecture en mode fullscreen. Si le paramètre est à false, le player reste en mode fullscreen, auterment  le player revient en mode embed.

useExternalFont

true | false

false

DEV | PROD

Permet redéfinir le font de player par défault. 

canCast

true | false

true

DEV | PROD

Active ChromeCast a true, le désactive a false. 
A true, le bouton apparait seulement sur Chrome. 

 isModeResume

true | false

false

DEV | PROD

Permet d'utiliser le mode résume.

time

int

0

DEV | PROD

Commence la lecture à une possition time (en seconde)

multiInstance

true | false

false 

DEV | PROD

Si true, les multiples players sur la page peuvent  jouer en même temps 

meta

object

null

DEV | PROD

Permet de définir certaines valeurs des métadonnées.

Liste des valeurs permises:

  • Program: Nom de l'émission / chaîne / film

  • Title: Titre de l'émission / Saison et épisode

  • teaserUrl: Url d'une image à utiliser pour le teaser ou un élément "picture" passé en chaîne de caractères ("<picure ..."). 

Exemple
meta: {
   Program: "Nom de l'émission",
   Title: "Saison 1 | épisode 2",
   teaserUrl: "http://path_to_image"
}

format9x16

true | false

false

DEV | PROD

Afficher le player en mode 9x16 et permettre une meilleure lecture des vidéos verticales

hideUI

true | false

false

DEV | PROD

Masquer l’interface utilisateur du player, à l’exception du bouton play pour démarrer une vidéo

loop

true | false

false

DEV | PROD

Lire le média en boucle



Explications des paramètres généraux

  • idClient : Marque radio-canadienne de votre projet: la version logicielle de la console peut changer d’un idClient à un autre. Si votre projet ne fait référence à aucune marque radio-canadienne (projet externe, contenu annonceur), vous n'avez pas à en tenir compte. 
  • appCode : Code de l’application d’où provient le média qui sera lu par la console. ( Exemple : medianet, medianetlive )


Important : Ne jamais utiliser le appcode live, toujours utiliser le appcode medianetlive pour les lives.

  • idMedia : Identifiant unique du média qui sera lu par la console.
  • params : Paramètres avancés permettant de personnaliser le comportement de  la console. Une section complète est disponible plus loin dans le document pour expliquer en détail ces paramètres.

User API

Le user API du lecteur est disponible en utilisant la variable avec laquelle le lecteur à été instancié: 

var player = RadioCanadaPlayer.initPlayerJs([video-element-container-id], [idMedia], [appCode], [params]);

On peut ensuite utilise l'API de cette façon:

player.api.play()

Les méthodes disponibles sont les suivantes:

MethodParamsDescription
translocate(<location>, <allowDuringAd = false>)

location (required) <string>: ID de l'élément du DOM vers lequel le lecteur sera déplacé. 

allowDuringAd (optinal) <boolean>: Permettre le déplacement durant les publicités.

Déplace le lecteur vers un autre conteneur. Il est important d'utiliser cette méthode puisqu’on doit réinitialiser certaines librairies.
play()NADémarre la lecture du média.
pause()NAPause la lecture du média.
setReduceMode(<reduced>)reduced (required) <boolean>: État "reduced" du lecteur.Informe le lecteur qu'il est en mode réduit ou non.
dispose()NADétruis l'instance actuelle du lecteur.
changeMedia(<idMedia>, <appCode>, <params>)

idMedia (required) <string>: ID du média à charger

appCode (required) <string>: appCode du média à charger

params (optinal) <object>: nouveaux paramètres d'intégrations

Change le média en cours.
getPlayerLog(<exportType>)exportType <string>: Type de retour voulu. Options possibles: DATA, CONSOLE, FILEPermets de récupérer les logs du lecteur. 
setAccessTokenApi(<accessToken>)accessToken <string>: Jeton d'accès provenant de la page. Permets d'aller récupérer les "claims" pour la lecture de contenus protégés.
volume(<level>)level <int>: Valeur de volume en pourcentagePermets d'ajuster le volume sans utiliser le UI.
mute()NAMute le son du lecteur
unMute()NAUnmute le son du lecteur.
seekTo(<time>)time <int>: Temps en seconde en rapport avec la durée du média.Déplace la lecture au temps donné
seekForward(<time>)time <int>: Nombre de secondes à avancer.Avance la lecture d'un certain nombre de secondes.
seekBack(<time>)time <int>: Nombre de secondes à reculer.Recule la lecture d'un certain nombre de secondes.
setCastMediaInfo(mediaInfo)Array<chrome.cast.media.MediaInfo>: array de media Set MediaInfo pour Cast avec enchaînement. 
fullscreen()NA Active ou désactive le mode plein écran.
focusOnPlay()
removeA11yFocus(Optinal) <bool>: Flag pour conserver le focus a11y Default false
Met le focus sur le bouton play/pause dans le bas du lecteur



Événements disponibles pour une instance du lecteur

Le lecteur est en mesure d'écouter ou d'émettre certains événements. Ceci est principalement utile lorsqu’on développe notre propre UI avec les lecteurs en mode API et aussi pour bien gérer la présence de plusieurs instances du player dans la même page.


Les événements du lecteur sont disponibles en utilisant la variable avec laquelle le lecteur a été instancié: 


var player = RadioCanadaPlayer.initPlayerJs([video-element-container-id], [idMedia], [appCode], [params]);


On peut ensuite avoir accès à la section d'événements du lecteur de cette façon:

player.events


Vous y trouverez 3 méthodes et l'objet suivants:

Nom 
Params
Description 
namesNARetourne la liste de noms des événements disponibles au lecteur. Voir la liste complète au bas de la page.
emit(<eventName>)eventName: Nom de l'événement disponible dans la variable "names" mentionné plus haut. Permet de lancer un évément javascript. 
on(<eventName>, <callback>)

eventName: Nom de l'événement disponible dans la variable "names" mentionné plus haut. 

callback: Fonction gérant le retour de l'événement. Des paramètres sont disponibles selon les événements.

Ajoute une écoute d'événement JavaScript (addEventListner)  
off(<eventName>)eventName: Nom de l'événement disponible dans la variable "names" mentionné plus haut. Retire l'écoute d'événement JavaScript (removeEventListner)  

Événements disponibles

Nom 
Description
AD_BREAK_COMPLETEFin d'une pause publicitaire (mid-roll).
AD_BREAK_STARTDébut d'une pause publicitaire (mid-roll).
AD_COMPLETEFin des publicités qui précède un média (pre-roll).
AD_ERRORErreur durant les publicités.
AD_PAUSELa lecture des publicités est en pause.
AD_STARTEDDébut des publicités.
ALL_ADS_COMPLETEToutes les publicités sont complétées pour le média actuel.
BEGINLancé dès que le média est demandé à jouer. 
BITRATE_CHANGEDChangement de résolution complété.
CAST_REQUESTEDIndique que l'utilisateur demande de faire CAST
CLOSING_CREDITSDébut du générique de fin de média.
CONTENT_ENDFin du média en cours.
DAI_COMPANIONS

Indique des des companions DAI sont disponibles sur la publicité DAI actuelle.

Arguments:
1. companions - Liste des companions disponibles pour la publicité en cours. Vide si aucun companion n'est disponible pour la publicité.

companions
type: array
[
   {
      size: "300x600", // dimensions du companion
      contentType: "image/jpeg", // type du companion
      content: "<div>...</div>" // contenu HTML du companion
   },
   ...
]

DISABLE_SHORTCUTSDésactivation des raccourcis claviers.
DISPOSEDestruction de l'instance du lecteur.
ENABLE_SHORTCUTSActivation des raccourcis claviers.
ENDMédia et postroll sont terminés.
ENTER_FULL_SCREENActivation du mode plein écran.
ERRORErreur survenue durant la lecture.
EXIT_FULL_SCREENSortie du mode plein écran.
LOAD_STARTDébut du chargement du média.
MEDIA_CHANGEDChangement de média terminé.
META_CHANGEDChangement des metas data terminé.
MUTELe volume du lecteur est passé en sourdine (muted)
PAUSELe média est en pause.
PLAYLecture du média.
PLAYINGLe média est présentement en lecture.
PLAYING_OUTSIDEUne autre instance de lecture démarre la lecture d'un média.
READYLe lecteur est prêt à jouer le média
REDUCESélection du mode réduit.
SEEK_ENDFin du "seek" media.
SEEK_STARTDébut du "seek" média.
STARTDébut de la lecture initiale d'un média.
TIME_UPDATE

Temps courant du média.

Arguments:
1. "timeState" (État du temps du média)

TimeState (État du temps du média)
type: object
{
   time: 152.464816, // Temps courant du média
   genericEndReached: false, // Le générique du média est-il atteint ?
   seeking: false // Le temps courant a-t-il été modifié par l'utilisateur ?
}

UNMUTELe volume du lecteur est passé à normal (unmuted)
VOLUME_CHANGEChangement au volume de lecture.
WAITINGLe lecteur est en attente de chargement.
WARNINGErreur non fatal. 

Voici la séquence des événements déclenchés dans le player durant la lecture:

META_CHANGED
BEGIN
PLAY
AD_BREAK_START
AD_STARTED
AD_COMPLETE
AD_BREAK_COMPLETE
START
PLAYING
ENABLE_SHORTCUTS
AD_BREAK_START
AD_STARTED
AD_COMPLETE
AD_STARTED
AD_COMPLETE
AD_STARTED
AD_COMPLETE
AD_BREAK_COMPLETE
PLAYING
CONTENT_END
AD_BREAK_START
AD_STARTED
AD_COMPLETE
AD_BREAK_COMPLETE
END


Considération pour le responsive

Afin que le player prenne automatiquement toute la largeur et hauteur disponible ( en fonction des dimensions du conteneur parent ), vous pouvez indiquer 100% pour les valeurs des paramètres avancées width et height.

Considération pour les appareils mobiles

Sur les appareils mobiles, le autoplay n’est pas supporté. De plus, la lecture de contenu doit toujours être initiée par une interaction usager. Ceci veut dire que si on utilise la fonction play(), celle-ci doit obligatoirement être appelée dans un gestionnaire d’événement initié par l’utilisateur (onClick ou autre). À notez qu’à cet effet, il est toujours mieux de privilégier click au lieu de touchstart, car ce dernier n’est pas considéré comme une interaction usager par Chrome.

Pour toutes questions ou commentaires

Veuillez contacter playerweb@radio-canada.ca