Ce guide explique comment maintenir un contrôle sur vos flux de Streaming Radio MP3/AAC ou HLS en activant la protection par clé unique (token) afin de décider p.ex si un auditeur peut écouter votre radio ou non.

Préambule

• Le principe est simple: à chaque connexion, vous effectuerez une requête vers l'API Infomaniak qui vous renverra en retour un token unique avec une durée de vie limitée et paramétrable. Ce token autorisera quiconque le possède à consommer le flux pendant cette période.
• Vous pouvez protéger un flux MP3/AAC ou HLS indépendamment l’un de l’autre (idem pour la géolocalisation d'ailleurs).
• L'activation de la restriction implique un changement de la configuration du flux qui peut prendre quelques minutes pour être répliquée sur les serveurs.

Protéger un flux audio par clé unique

Pour ce faire, il suffit de se rendre dans les paramètres de restrictions et d'activer la protection par token sur le flux que vous souhaitez sécuriser:

1. Cliquez ici afin d'accéder à la gestion de votre produit sur le Manager Infomaniak (besoin d'aide ?).
2. Cliquez directement sur le nom attribué au produit concerné.
3. Cliquez sur le nom du flux audio concerné.
4. Cliquez sur Restrictions dans le menu latéral gauche.
5. Choisissez HLS si nécessaire.
6. Cliquez sur le menu d'action ⋮ situé à droite de l'élément concerné.
7. Cliquez sur Restriction par token:
   
    

Activez ensuite la protection.

Attention, au moment où vous allez activer cette option, l'accès au flux sera instantanément bloqué pour les nouvelles connexions. Adaptez vos Players pour prendre en compte la restriction, comme illustré dans l'exemple ci-dessous :

Créer un token API Radio

Pour avoir accès à l'API Radio, vous devez en premier lieu vous authentifier grâce à un token application. Cette étape n'est à faire qu'une seule fois. Pour créer ce token d'application, prenez connaissance de cet autre guide.

Le scope est radio et la durée de vie illimité pour éviter de devoir régénérer un code de manière régulière. Une fois le token généré, le copier afin de le coller dans l'exemple ci-dessous.

Exemple d'utilisation en langage PHP

Pour MP3/AAC ou HLS, le code peut être sensiblement le même, seule l'URL appelée en POST change au niveau de sa forme.

if (!defined('API_TOKEN')) {
     define('API_TOKEN', 'AYF5lSh3c7Xy5974Fs12RTkTThujT-L9R4Xk2ZfGyP6sV7QqJ1oC3jD8nFtKzIxUeMw5oNzR6');
}
/**
 * Fonction générique pour executer des requêtes cURL
 *
 * @param string $method Méthode HTTP (GET, POST, PUT, etc...)
 * @param string $url Url de l'api a requêter
 * @param array $headers Liste des en-têtes HTTP (l'autorisation doit être passée ici avec un ['Authorization: Bearer ']
 * @param array $payload Un tableau contenant les données pour créer un token
 * @return mixed
 */

function request(string $method, string $url, array $headers = [], array $payload = []): mixed{
    // prepare options array
    $opts = [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_URL => $url,
        CURLOPT_CUSTOMREQUEST => strtoupper($method),
    ];

    // add payload if relevant
    if ($payload && $method !== 'GET') {
        $opts[CURLOPT_POSTFIELDS] = json_encode($payload);
    }
    $ch = curl_init();
    curl_setopt_array($ch, $opts);
    $result = curl_exec($ch);
    if(curl_errno($ch)){
        throw new Exception(curl_error($ch));
    }
    $data = json_decode($result, true);
    if ($data['result'] === 'error') {
        throw new Exception($data['error']['description'] ?? 'an error occured');

    }
    return $data['data'];
}

On va créer le token, l'URL de création du token se décompose comme suit :

• Pour un flux MP3 / AAC

POST https://api.infomaniak.com/1/radios/acl/streams/mountpoint.mp3/token

Exemple pour protéger https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac la route sera: https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token

• Pour un flux HLS

POST https://api.infomaniak.com/1/radios/acl/hls_streams/<stream>/token

Exemple pour protéger https://myradiostream.radiohls.infomaniak.com/myradiostream/manifest.m3u8 la route sera: https://api.infomaniak.com/1/radios/acl/hls_streams/myradiostream/token

Exemple dans le cas du MP3 / AAC, pensez à ajuster :

$token = request(
    'POST',
   'https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token',
    // en-tête d'authorization
    [
        'Authorization: Bearer ' . API_TOKEN,
        'Content-Type: application/json',
    ],
    /**
     * payload pour créer le token, vous pouvez passer les valeurs suivantes
     * window     | 300               | optionnel | durée de validité du token (default: 5 minutes)
     */

    [
        'window' => 3600, // 1h validity
    ]
);

Il est important de noter que si ce code est généré au moment du chargement de la page, l'auditeur aura "window" secondes pour lancer la lecture du flux. Au-delà de ce délai, le token expirera, et le flux ne pourra plus être lancé à moins que la page ne soit rechargée. Selon vos besoins et votre cas d'utilisation, il sera nécessaire d'ajuster ce délai de la meilleure manière possible.

Il faudra également remplacer ci-dessous l'URL de lecture de votre flux à la place de celle indiqué tout en conservant le paramètre $token à la fin. Et pour finir, on affiche le Player (ici une simple balise html5, mais on peut ajouter bien sûr n'importe quelle surcouche après, le token étant passé dans les paramètres $_GET de l'url).

$streamUrl = "https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac?$token";
echo "<audio controls=""><source src="$streamUrl"></audio>";

Ce guide détaille la configuration d'un Player pour votre Streaming Radio Infomaniak.

Prérequis

• Ajouter 1 Player utilisant le modèle Infomaniak.

Configurer les options du Player Infomaniak

Une fois que vous avez lié votre flux à votre Player et que votre Player est créé:

1. Cliquez ici afin d'accéder à la gestion de votre produit sur le Manager Infomaniak (besoin d'aide ?).
2. Cliquez directement sur le nom attribué au produit concerné.
3. Cliquez sur Mes players dans le menu latéral gauche.
4. Cliquez sur le nom du Player à configurer (ou créez un nouveau lecteur):
   

1. Onglet Apparence

C'est ici que vous pouvez choisir la taille du lecteur (grande, moyenne, mini, ou lecteur multi radios) et son pourcentage d'affichage.

Vous pouvez personnaliser les couleurs du fond, des boutons et du texte:

Un bouton à bascule (toggle switch) permet d'activer ou désactiver l'affichage des morceaux diffusés, avec ou sans leurs heures de diffusion:

• Prenez connaissance des détails à ce sujet en fin de ce guide.

Le Player peut afficher:

• une illustration représentant la jaquette de l’album, ou une image de substitution si elle n’est pas disponible,
• une image fixe (3 Mo max.),
• le logo de votre radio, à personnaliser ici:
  
• une visualisation du spectre audio (Spectrogramme / Spectrum).

2. Onglet Diffusion

C'est ici que vous pouvez lier vos flux radio (HLS ou pas) à votre Player en cours de configuration.

Prenez connaissance de cet autre guide au sujet des choix proposés concernant la gestion du direct:

3. Onglet Vignettes

C'est ici que vous pouvez charger les images visibles lorsque le flux est en chargement, ou indisponible/restreint.

4. Onglet Informations du lecteur

C'est ici que vous pouvez nommer votre Player et décider d'afficher ou masquer:

• le titre et l'artiste à la place du nom de la radio,
• le nombre d'auditeurs,
• le logo Infomaniak.

5. Onglet Options de partage

Un bouton à bascule (toggle switch) permet d'activer ou désactiver certains services comme Facebook. Une fois activé, un bouton de partage vers ces services sera visible sur votre Player:

Détails de l'historique de diffusion (onglet #1)

L'historique de diffusion permet de réécouter les musiques diffusées (entre 1 et 40) si votre flux est de type HLS uniquement (vous pourrez alors définir une mémoire tampon (buffer) allant de 25 secondes à 2 heures):

La fonctionnalité de retour arrière et de réécoute n'est pas activée par défaut : elle reste optionnelle afin de respecter les restrictions de certains pays ou radios. Une fois activée, le gestionnaire de la radio peut choisir quels flux seront disponibles à la diffusion (cf onglet #2 ci-dessus), tandis que l'auditeur peut sélectionner la qualité d'écoute dans le Player:

Position & intégration de l'historique de diffusion

La liste est consultable à choix:

• directement sous le Player,
• sur le Player,
• ou déportable dans l'intégration de votre site Web…

En effet, il est possible d'afficher l'historique dans une seconde iframe, distincte de celle du Player principal. Exemple d'URL pour le Player :
https://player-radio.infomaniak.com/2/prod/super/7cbaa24a-3510-47a4-b41e-b99218bfd507

Et pour l'historique déporté :
https://player-radio.infomaniak.com/2/prod/history

Les deux iframes doivent être intégrées sur la même page et communiquent entre elles pour mettre à jour l'historique ou lancer un titre précédemment diffusé.

Un second mode d'intégration permet d'afficher un historique autonome, sans iframe principale. Il suffit d'ajouter l'ID du Player à l'URL :
https://player-radio.infomaniak.com/2/prod/history/7cbaa24a-3510-47a4-b41e-b99218bfd507

Ce mode convient par exemple aux utilisateurs d'un autre Player souhaitant afficher uniquement l'historique des titres.

Ce guide explique comment transférer les flux audio présents sur l'un de vos Streaming Radio Infomaniak vers l'une de vos autres radios, présente sur la même Organisation.

Transférer les flux audio

Pour cela: 

1. Cliquez ici afin d'accéder à la gestion de votre produit sur le Manager Infomaniak (besoin d'aide ?).
2. Cliquez directement sur le nom attribué au produit concerné.
3. Cliquez sur le menu d'action ⋮ situé à droite de l'élément concerné.
4. Choisissez Transférer:
   
5. Cherchez et validez le nom de l'autre radio que vous possédez dans la même Organisation.
6. Validez le transfert:
   

Rafraichissez les pages du Manager si nécessaire pour actualiser les informations affichées.