Base de connaissances

Le format AAC (Advanced Audio Coding) a été choisi comme principal format de fichier par la société Apple dans les iPod ou dans son logiciel iTunes. Le AAC+ appelé également HE AAC est une amélioration du codec audio AAC, suivie par une autre version appelée HE AAC v2.

Nous vous recommandons l'AAC+ plutôt que le MP3: un flux à 32 kbps en AAC+ a une qualité légèrement inférieure à un flux à 128 kbps en MP3 et largement supérieure à un flux à 64 kbps en MP3.

Ce guide concerne les informations d'écoute de Streaming Radio qui peuvent être exportées grâce au protocole FTP. Les logs sont alors automatiquement transférés par FTP pour être ensuite traités (attention, l'opération nécessite des connaissances de programmation).

Préambule

• Les logs de votre radio seront fournis sous forme de fichier compressé xyz.mp3-20140805.log.gz (la date du log est sous forme YYYYMMDD).
• Chaque log commence à 04:00 heure suisse et finit à 03:59:59 le lendemain.
• Le log est sous la forme ip user-identifier authuser [date-time] "request" status octets "referer" "useragent" listening-time:

  • 81.56.215.98 - - [09/Apr/2009:08:23:18 +0200] "GET /toto.mp3 HTTP/1.1" 200 1211297 "-" "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.0.8) Gecko/2009032711 Ubuntu/8.10 (intrepid) Firefox/3.0.8" 69

  • Il peut arriver que la ligne de log soit mal formée, à cause d'un referer trop long p.ex. Ce comportement d'Icecast ne peut être modifié.
• Les adresses de la rangée IP 84.16.67.128/25 doivent être ignorées car ce sont les serveurs de streaming.
• Depuis la page des paramètres sur le Manager, vous pouvez redemander les logs des jours passés.

Activer l'envoi de logs par FTP

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 nom du flux audio concerné.
4. Cliquez sur Paramètres dans le menu latéral gauche.
5. Activez l'export de logs par FTP avec le bouton à bascule (toggle switch).
6. Entrez un nom d'hôte: adresse du serveur FTP.
7. Entrez un nom d'utilisateur: nom du compte FTP.
8. Entrez un mot de passe: celui du compte FTP.
9. Entrez le répertoire sur le serveur dans lequel stocker les logs.
10. Cliquez sur le bouton Enregistrer en bas de page:
    

Traiter les logs

Le mieux est d'utiliser une expression régulière comme celle ci-dessous: 

"/^(\S+)\s(.+)\s(\S+)?\s\[((\d\d)\/([a-zA-Z]{3,3})\/(\d\d\d\d)\:(\d\d)\:(\d\d)\:(\d\d)\s\+\d\d\d\d)\]\s"GET\s\/([\-a-z0-9]{1,40}(\.)?(mp3|aac|ogg){0,1})(.*)?"\s(\d{3,3})\s(\d+)\s"(.+)"\s"(.+)"\s(\d+)$/i";

Cette syntaxe est celle de la fonction PHP preg_match et devra être adaptée si d'autres fonctions/langages sont utilisés.

La fonction preg_match donne un tableau dont voici les positions significatives: 

Ce guide explique comment transmettre les metadata (métadonnées) pour le flux radio envoyé depuis votre encodeur de Streaming radio .

Utiliser l'URL à disposition

Il suffit de faire un GET sur une URL de type:

https://[flux]:[password]@api.infomaniak.com/1/radios/stats/metadata?data=artist - title

L'URL au complet est disponible sur l'interface d'administration:

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 Paramètres dans le menu latéral gauche.
5. Cliquez sur le bouton pour copier le lien des métadata:
   

En savoir plus

Pour les développeurs qui coderaient un Player, il existe des librairies qui peuvent chercher l'info transmise et l'afficher car dans les données du flux, les données sont transmises. L'autre possibilité est de récupérer les infos du flux sur le serveur lui-même. 

Ce guide explique comment retirer un flux audio de votre Streaming Radio, sans supprimer le produit complet.

Effacer une radio

Afin d'accéder au service de Streaming et de supprimer un des flux :

1. se connecter au Manager Infomaniak (manager.infomaniak.com) depuis un navigateur Web comme Brave ou Edge
2. cliquer sur l'icône ‍ en haut à droite de l'interface (ou naviguer grâce au menu latéral gauche p.ex)
3. choisir Streaming radio (univers Streaming)
4. cliquer sur le nom de l'objet concerné dans le tableau qui s'affiche
5. cliquer sur le menu d'action ⋮ à droite de l'objet concerné dans le tableau qui s'affiche
6. cliquer sur Supprimer
   
7. entrer le mot de passe de votre compte et valider la suppression

Ce guide explique comment spécifier un flux audio de secours sur le Streaming radio Infomaniak.

Ainsi si votre flux principal devient indisponible, le flux de secours prendra automatiquement le relais de la diffusion.

Créer un flux de secours

Afin d'accéder au service de Streaming radio :

1. cliquer ici afin d'accéder à la gestion de votre produit sur le Manager Infomaniak (besoin d'aide ?)
2. cliquer directement sur le nom attribué au produit concerné
3. cliquer sur le nom de la radio
4. cliquer sur le bouton Ajouter un flux pour créer un nouveau flux et lui joindre un flux de secours ou Configurer un flux existant afin d'activer l'option:
   
5. cliquer sur le bouton à bascule (toggle switch) pour activer le flux de secours sur votre flux:
   
6. copier les informations à votre disposition afin de paramétrer votre encodeur de secours
7. enregistrer l'activation du flux de secours en bas à droite de la page

Au même endroit vous pouvez définir le flux de secours comme étant un relais de flux afin d'entrer manuellement les paramètres correspondants au flux audio de secours:

Enregistrer les nouvelles informations en bas à droite de la page.

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, lire ce 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>";