Questa guida riguarda il controllo del live (timeshift) che permette ai tuoi ascoltatori di mettere in pausa, tornare indietro e poi tornare al live sui tuoi flussi HLS, con una profondità di ritorno fino a 2 ore.

Premessa

• A differenza del Streaming Video, non esiste uno strumento di pianificazione del Timeshift lato Radio.
• La ri-ascolto/riavvolgimento è disattivata per impostazione predefinita sul Player per lasciarti il controllo sull'esposizione al pubblico.

Offrire il controllo del live agli ascoltatori

Prerequisiti

• Creare o modificare un flusso HLS nel tuo prodotto Streaming Radio.

Successivamente:

1. Durante la creazione (o modifica) di un flusso HLS, definisci il buffer tra 00:00:25 e 02:00:00. Questo valore, compreso tra 25 secondi e 2 ore, corrisponde alla durata massima durante la quale gli ascoltatori possono tornare indietro e mettere in pausa il live, prima di tornare in diretta. Determina la profondità del controllo del live. Esempi:
   • 00:00:25 → 05:00: tolleranza minima per brevi pause.
   • 10:00 → 30:00: ideale per i formati news / talk.
   • 30:00 → 02:00:00: comfort massimo per programmi musicali e eventi.
2. Attivare la ri-ascolto nel tuo Player (consulta questa altra guida) se desideri offrirla al pubblico (disattivata per impostazione predefinita).

SpacialAudio SAM Cast è compatibile con l'offerta di streaming audio.

Questa guida dettaglia la configurazione di un Player per la tua Radio in Streaming Infomaniak.

Prerequisiti

• Aggiungi 1 Player utilizzando il modello Infomaniak.

Configurare le opzioni del Player Infomaniak

Una volta che hai collegato il tuo flusso al tuo Player e che il tuo Player è creato:

1. Clicca qui per accedere alla gestione del tuo prodotto sul Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome attribuito al prodotto interessato.
3. Clicca su I miei player nel menu laterale sinistro.
4. Clicca sul nome del Player da configurare (o aggiungi un nuovo lettore cliccando sul pulsante sopra):
   

1. Scheda Aspetto

È qui che puoi scegliere la dimensione del lettore (grande, media, mini, o lettore multi radio) e la sua percentuale di visualizzazione.

Puoi personalizzare i colori dello sfondo, dei pulsanti e del testo:

Un pulsante a scorrimento (toggle switch) permette di attivare o disattivare la visualizzazione dei brani trasmessi, con o senza le loro ore di trasmissione:

• Prendi visione dei dettagli a riguardo alla fine di questa guida.

Il Player può visualizzare:

• un'illustrazione che rappresenta la copertina dell'album, o un'immagine di sostituzione se non è disponibile,
• un'immagine fissa (3 Mo max.),
• il logo della tua radio, da personalizzare qui:
  
• una visualizzazione dello spettro audio (Spettrogramma / Spettro).

2. Scheda Trasmissione

È qui che è possibile collegare i propri flussi radio (HLS o meno) al proprio Player in fase di configurazione.

Prendere visione di questa altra guida riguardo alle scelte proposte in merito alla gestione del live:

3. Scheda Miniature

È qui che è possibile caricare le immagini visibili quando il flusso è in caricamento o indisponibile/limitato:

4. Scheda Informazioni del lettore

È qui che è possibile nominare il proprio Player e decidere di visualizzare o nascondere:

• il titolo e l'artista al posto del nome della radio,
• il numero di ascoltatori,
• il logo Infomaniak.

5. Scheda Opzioni di condivisione

Un pulsante a scorrimento (toggle switch) permette di attivare o disattivare alcuni servizi come Facebook:

Una volta attivato, un pulsante di condivisione verso questi servizi sarà visibile sul Player:

Dettagli della cronologia di trasmissione (scheda #1)

La cronologia di trasmissione permette di riascoltare le musiche trasmesse (tra 1 e 40) se il proprio flusso è di tipo HLS esclusivamente (è quindi possibile definire una memoria tampone (buffer) che va da 25 secondi a 2 ore):

La funzionalità di ritorno indietro e di riascolto non è attivata per impostazione predefinita: rimane opzionale per rispettare le restrizioni di alcuni paesi o radio. Una volta attivata, il gestore della radio può scegliere quali flussi saranno disponibili per la trasmissione (vedi scheda #2 sopra), mentre l'ascoltatore può selezionare la qualità di ascolto nel Player:

Posizione e integrazione della cronologia di trasmissione

L'elenco è consultabile a scelta:

• direttamente sotto il Player,
• sul Player,
• o spostabile nell'integrazione del proprio sito Web…

In effetti, è possibile visualizzare la cronologia in una seconda iframe, distinta da quella del Player principale. Esempio di URL per il Player:
https://player-radio.infomaniak.com/2/prod/super/7cbaa24a-3510-47a4-b41e-b99218bfd507

E per la cronologia esportata:
https://player-radio.infomaniak.com/2/prod/history

I due iframe devono essere integrati nella stessa pagina e comunicano tra loro per aggiornare la cronologia o avviare un titolo precedentemente trasmesso.

Un secondo modo di integrazione permette di visualizzare una cronologia autonoma, senza iframe principale. Basta aggiungere l'ID del Player all'URL:
https://player-radio.infomaniak.com/2/prod/history/7cbaa24a-3510-47a4-b41e-b99218bfd507

Questa modalità è adatta, ad esempio, agli utenti di un altro Player che desiderano visualizzare solo la cronologia dei titoli.

Questa guida presenta HLS, che segmenta il tuo audio per una trasmissione HTTP affidabile, compatibile e altamente distribuibile, ideale per un pubblico mobile e numeroso.

Cos'è HLS?

HLS (HTTP Live Streaming) è un protocollo di streaming che divide l'audio in piccoli segmenti di pochi secondi e pubblica un manifesto .m3u8 che elenca questi segmenti. Il Player scarica questi segmenti tramite HTTP/HTTPS (porte 80/443), facilitando la memorizzazione nella cache, la ripresa dopo interruzioni e la distribuzione su larga scala.

Nel tuo servizio di Streaming Radio, l'attivazione di HLS aggiunge un flusso aggiuntivo dedicato. Ha la propria URL di ascolto (manifesto HLS) e può essere selezionato e prioritizzato nel Player infomaniak. Il flusso HLS coesiste con i tuoi flussi storici (es. MP3/AAC), senza interruzioni del servizio.

Vantaggi per un flusso radiofonico

• Compatibilità estesa: supporto nativo su iOS/iPadOS (Safari) e ampia compatibilità tramite lettori HTML5 moderni e applicazioni di terze parti.
• Scalabilità e prestazioni: trasmissione via HTTP(S) facilmente distribuibile tramite CDN e cache; migliore scalabilità rispetto a un singolo flusso continuo.
• Robustezza: in caso di micro-interruzioni, il lettore può recuperare i segmenti successivi e riprendere rapidamente; meno sensibile alle perdite momentanee.
• Attraversamento delle reti: funziona su 80/443, generalmente meglio accettato dai firewall e proxy aziendali rispetto a certi flussi “ICY”.
• HTTPS semplificato: consegna sicura senza plugin o protocolli esotici.
• Adattamento del bitrate (ABR): quando vengono offerte più varianti, il lettore può passare automaticamente in base alla qualità della rete per limitare le interruzioni in mobilità.
• Flessibilità di integrazione: un punto di ascolto distinto permette di esporre HLS come flusso principale, secondario o di backup nel tuo Player.

Specifiche e punti di attenzione

• Latenza: HLS aggiunge una latenza generalmente di qualche decina di secondi (legata alla dimensione dei segmenti e al buffering). È normale per questo protocollo.
• Lettore compatibile richiesto: utilizza il player infomaniak o un lettore/web SDK che supporti i manifesti .m3u8.
• Parco eterogeneo: alcuni ricevitori hardware obsoleti (webradio, autoradio IP) accettano solo flussi MP3/Icecast; conserva le loro URL storiche in parallelo.
• ABR condizionale: l'adattamento del bitrate è efficace solo se vengono pubblicati più profili; in mancanza, il flusso HLS rimane funzionante in qualità unica.

Questa guida spiega come mantenere il controllo sui flussi di Streaming Radio MP3/AAC o HLS attivando la protezione con chiave unica (token) per decidere, ad esempio, se un ascoltatore può ascoltare la tua radio o meno.

Premessa

• Il principio è semplice: ad ogni connessione, effettuerai una richiesta all'API Infomaniak che ti restituirà un token unico con una durata limitata e configurabile. Questo token autorizzerà chiunque lo possieda a consumare il flusso durante questo periodo.
• È possibile proteggere un flusso MP3/AAC o HLS indipendentemente l'uno dall'altro (stesso discorso per la geolocalizzazione).
• L'attivazione della restrizione comporta una modifica della configurazione del flusso che può richiedere alcuni minuti per essere replicata sui server.

Proteggere un flusso audio con chiave unica

Per farlo, basta andare nelle impostazioni delle restrizioni e attivare la protezione con token sul flusso che si desidera proteggere:

1. Clicca qui per accedere alla gestione del tuo prodotto sul Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome attribuito al prodotto interessato.
3. Clicca sul nome del flusso audio interessato.
4. Clicca su Restrizioni nel menu laterale sinistro.
5. Seleziona HLS se necessario.
6. Clicca sul menu di azione ⋮ situato a destra dell'elemento interessato.
7. Clicca su Restrizione con token:
   
    

Attiva quindi la protezione.

Attenzione, al momento in cui attiverai questa opzione, l'accesso al flusso sarà immediatamente bloccato per le nuove connessioni. Adatta i tuoi Player per tenere conto della restrizione, come illustrato nell'esempio qui sotto:

Creare un token API Radio

Per accedere all'API Radio, devi prima autenticarti con un token di applicazione. Questa operazione va fatta una sola volta. Per creare questo token di applicazione, consulta questa altra guida.

Il campo di applicazione è radio e la durata illimitata per evitare di dover rigenerare un codice in modo regolare. Una volta generato il token, copiarlo per incollarlo nell'esempio qui sotto.

Esempio di utilizzo in linguaggio PHP

Per MP3/AAC o HLS, il codice può essere sostanzialmente lo stesso, cambia solo l'URL chiamata in POST a livello della sua forma.

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'];
}

Vogliamo creare il token, l'URL di creazione del token si scompone come segue:

• Per un flusso MP3/AAC

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

Esempio per proteggere https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac la rotta sarà: https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token

• Per un flusso HLS

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

Esempio per proteggere https://myradiostream.radiohls.infomaniak.com/myradiostream/manifest.m3u8 la rotta sarà: https://api.infomaniak.com/1/radios/acl/hls_streams/myradiostream/token

Esempio nel caso del MP3/AAC, ricordati di regolare:

$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
    ]
);

È importante notare che se questo codice viene generato al momento del caricamento della pagina, l'ascoltatore avrà "window" secondi per avviare la riproduzione del flusso. Oltre questo periodo, il token scadrà e il flusso non potrà più essere avviato a meno che la pagina non venga ricaricata. A seconda delle vostre esigenze e del vostro caso d'uso, sarà necessario regolare questo periodo nel modo migliore possibile.

Sarà anche necessario sostituire qui sotto l'URL di lettura del vostro flusso al posto di quella indicata mantenendo il parametro $token alla fine. E per finire, visualizziamo il Player (qui una semplice etichetta html5, ma è possibile aggiungere ovviamente qualsiasi sovrapposizione dopo, il token essendo passato nei parametri $_GET dell'url).

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

Questa guida spiega come trasferire i flussi audio presenti su una delle tue Radio Streaming Infomaniak verso un'altra delle tue radio, presente nella stessa Organizzazione.

Trasferire i flussi audio

Per fare questo:

1. Clicca qui per accedere alla gestione del tuo prodotto su Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome attribuito al prodotto interessato.
3. Clicca sul menu delle azioni ⋮ situato a destra dell'elemento interessato.
4. Scegliere Trasferire:
   
5. Cerca e conferma il nome dell'altra radio che possiedi nella stessa Organizzazione.
6. Conferma il trasferimento:
   

Aggiorna le pagine del Manager se necessario per aggiornare le informazioni visualizzate.