Intégrez un lecteur de playlist

Deux lignes pour démarrer

Installez le SDK, pointez un conteneur, donnez l’identifiant de votre playlist.

npm install js-streamlike-sdk

<div id="mon-lecteur"></div>

<script type="module">
    import { generatePlaylistPlayer } from 'js-streamlike-sdk';

    const lecteur = await generatePlaylistPlayer('mon-lecteur', {
        playlistId: 'c4da86fddd8f0ada'
    });
</script>

À ce stade, vous avez déjà un lecteur fonctionnel : les médias sont récupérés dans l’ordre de la playlist, le premier est chargé, la liste s’affiche à droite avec les vignettes et les durées, les boutons précédent / suivant sont actifs, et la vidéo suivante démarre à la fin de la précédente.

Voici ce que donne ce code, sur la playlist de démonstration Streamlike :

Le lecteur accepte aussi une vue (viewId), une société (companyId), ou directement un tableau de médias que vous avez déjà récupéré (medias) — pratique si votre page appelle le webservice pour d’autres raisons. Les paramètres de tri et de filtrage du webservice restent accessibles via playlistParams.

Sans rien installer

Le SDK n’a aucune dépendance : les fichiers publiés sont directement utilisables par un navigateur, depuis un CDN npm comme jsDelivr ou unpkg. Ni installation, ni étape de build — de quoi monter un prototype, une page isolée ou un site que vous ne compilez pas.

<div id="mon-lecteur"></div>

<script type="module">
    import { generatePlaylistPlayer } from 'https://cdn.jsdelivr.net/npm/js-streamlike-sdk@3.7.0/dist/index.mjs';

    await generatePlaylistPlayer('mon-lecteur', { playlistId: 'c4da86fddd8f0ada' });
</script>

Si votre page ne peut pas utiliser les modules ES — un CMS, un gabarit ancien —, une seconde version expose tout le SDK sur une variable globale :

<script src="https://cdn.jsdelivr.net/npm/js-streamlike-sdk@3.7.0/dist/index.global.js"></script>
<script>
    Streamlike.generatePlaylistPlayer('mon-lecteur', { playlistId: 'c4da86fddd8f0ada' });
</script>

Un conseil : épinglez toujours une version précise. Avec @latest, une publication future modifierait le comportement de pages que vous ne maîtrisez plus. Et gardez en tête qu’un CDN public ajoute un tiers dans vos pages : les intégrations qui ne peuvent pas l’accepter passeront par npm et serviront le SDK depuis leur propre domaine.

Choisir les informations affichées

C’est le réglage qui change tout selon le contexte : une page d’actualités n’affiche pas les mêmes métadonnées qu’un espace de formation. L’option info liste ce qui apparaît pendant la lecture.

const lecteur = await generatePlaylistPlayer('mon-lecteur', {
    playlistId: 'c4da86fddd8f0ada',
    locale: 'fr-FR',
    info: {
        title: true,
        description: true,
        releaseDate: true,
        releaseTime: true,
        keywords: true
    },
    labels: { previous: 'Précédent', next: 'Suivant' }
});

L’option locale gouverne le formatage des dates, des heures et du nombre de lectures. Les textes de l’interface, eux, se remplacent via labels.

La même logique s’applique aux entrées de la liste avec listItem : vignette, numéro, titre, durée, description. Et si vous voulez que les vignettes s’animent au survol, passez-leur les options de l’aperçu interactif :

listItem: {
    interactiveThumbnail: { mode: 'animation' }
}

Les playlists longues

Une playlist de trois cents vidéos ne se charge pas d’un bloc. Le lecteur en récupère dix, puis étend la liste au fur et à mesure de la lecture : en arrivant sur la neuvième, les dix suivantes sont déjà en route. Un bouton « plus » reste disponible sous la liste tant qu’il y a des vidéos à charger, et le compteur indique où vous en êtes — « 20 / 330 ».

Rien à régler pour que ce soit le cas. Si vous préférez tout charger d’un coup, sur une playlist courte ou une page qui doit être complète immédiatement, augmentez la taille de page :

await generatePlaylistPlayer('mon-lecteur', {
    playlistId: 'c4da86fddd8f0ada',
    pageSize: 500
});

Une réserve sur les longues listes : les vignettes animées téléchargent le storyboard de chaque vidéo dès son affichage. Sur une vitrine de quelques dizaines d’entrées, l’effet vaut le coût ; sur trois cents, cela fait autant de requêtes. La vignette fixe, appliquée par défaut, est le bon choix au-delà.

Un lien qui démarre au bon endroit

Le cas classique : quelqu’un veut partager le passage à 1 min 05 de la troisième vidéo. Deux options suffisent.

await generatePlaylistPlayer('mon-lecteur', {
    playlistId: 'c4da86fddd8f0ada',
    startMediaId: '4402e821e35336c5',
    startTimecode: '00:01:05'
});

Le timecode accepte des secondes (65) ou un format horaire (00:01:05.500). Si le média demandé n’appartient pas à la playlist, le lecteur repart sur le premier plutôt que de rester vide.

Pour automatiser l’aller-retour, activez shareParams : le lecteur lit alors ?media=...&t=... dans l’URL de la page, et sait générer ce même lien pour la position en cours.

const lecteur = await generatePlaylistPlayer('mon-lecteur', {
    playlistId: 'c4da86fddd8f0ada',
    shareParams: { enabled: true }
});

document.getElementById('partager').addEventListener('click', () => {
    navigator.clipboard.writeText(lecteur.getShareUrl());
});

Le nom des deux paramètres d’URL est configurable, au cas où media et t seraient déjà pris sur votre site.

Piloter le lecteur depuis votre page

generatePlaylistPlayer renvoie un contrôleur. Vous n’êtes donc pas limité aux boutons fournis : un sommaire maison, un raccourci clavier ou un chapitrage externe peuvent commander la lecture.

lecteur.next();                          // média suivant
lecteur.playIndex(2, 30);                // 3e média, à 30 secondes
lecteur.playMedia('4402e821e35336c5');   // par identifiant
lecteur.seek(120);                       // se positionner dans le média courant
lecteur.getCurrentMedia();               // les métadonnées du média en cours
lecteur.loadMore();                      // charger la page de médias suivante
lecteur.getTotal();                      // le nombre total de vidéos de la playlist
lecteur.destroy();                       // tout retirer proprement

Deux rappels complètent l’ensemble : onMediaChange(media, index) à chaque changement de vidéo — pratique pour votre outil de mesure d’audience — et onPlaylistEnd() quand la dernière se termine, si vous voulez enchaîner sur autre chose. Avec loop: true, la playlist repart au début.

Habiller le lecteur

Chaque élément généré porte une classe préfixée, sl-playlist par défaut : sl-playlist-info-title, sl-playlist-item, sl-playlist-button-next… La feuille de style embarquée n’utilise que des sélecteurs de classe simples, vos règles la surchargent donc sans bataille de spécificité ni !important.

.sl-playlist-info-title {
    font-family: "Votre police", sans-serif;
    color: #293c5a;
}

.sl-playlist-item.is-active > .sl-playlist-item-button {
    box-shadow: inset 3px 0 0 #293c5a;
}

Le média en cours de lecture porte la classe is-active dans la liste. Si vous préférez repartir d’une page blanche, injectStyles: false désactive la feuille par défaut ; classPrefix renomme l’ensemble des classes pour les aligner sur votre convention. La position de la liste se règle avec listPosition : right, left, bottom ou top.

Un détail qui fait gagner du temps

autostart: true demande au lecteur de démarrer seul. Les navigateurs, eux, bloquent la lecture automatique avec le son : sur une page où le visiteur n’a encore rien cliqué, ajoutez muted: true dans playerParams si vous tenez au démarrage immédiat. En navigation à l’intérieur de la playlist, la question ne se pose plus — le clic de l’internaute vaut autorisation, et chaque vidéo suivante démarre d’elle-même.

À vous d’essayer

Partez du minimum, activez les informations qui comptent pour votre page, puis branchez le partage timecodé. La démo livrée avec le SDK (demo/playlist-player.html) permet de basculer chaque option à la volée pour trouver le bon réglage avant de l’écrire dans votre code.