123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168 |
- = Radiomanifest specification
- CiurmaPirata
- Un formato per fare sì che il sito di una radio possa esporre in maniera strutturata alcune informazioni sul
- suo sito.
- Tali informazioni sono, brevemente:
- * il palinsesto
- * l'elenco delle trasmissioni che vanno in onda in modo regolare, e per ciascuna di esse i principali feed
- * gli indirizzi di streaming
- Per permettere un'implementazione più semplice, ciascuna di queste informazioni segue una sua specifica, possibilmente appoggiandosi a specifiche già esistenti.
- == RadioManifest
- Al fine di avere un singolo punto in cui "esporre" le funzionalità supportate dal sito web, un sito può creare un manifest. Esso *DOVREBBE* (*SHOULD*) chiamarsi sempre ``${BASEURL}/radiomanifest.xml``.
- Ecco un esempio di xml:
- <?xml version="1.0" encoding="UTF-8" ?>
- <radio-manifest>
- <schedule src="https://www.radioexample.org/palinsesto.ics" />
- <streaming>
- <source name="hi-quality" priority="100" src="https://www.radioexample.org/stream.m3u" />
- <source name="lo-quality" priority="50" src="https://www.radioexample.org/stream-low.m3u" />
- </streaming>
- <shows src="https://www.radioexample.org/shows.xml" />
- <feed src="https://www.radioexample.org/all.xml" />
- </radio-manifest>
- (link:radio-manifest.xsd[Schema XSD])
- Ovvero:
- * 0 o 1 ``schedule``. Gli schedule sono definiti in link:https://icalendar.org/RFC-Specifications/iCalendar-RFC-5545/[formato iCalendar]
- * 0 o 1 oggetti ``streaming``; contengono un qualsiasi numero (almeno 1) di source, le quali
- ** *POSSONO* avere un campo ``name``. Il campo ``name`` è fortemente
- raccomandato se viene fornito più di un oggetto ``streaming``
- ** *DEVONO* avere un campo ``src``, il quale deve puntare ad una risorsa di tipo M3U.
- ** *POSSONO* avere un campo ``priority``, contenente un valore intero; se omesso, si assume il valore "1". Un numero più grande indica una
- maggiore importanza. Il campo ``priority`` serve a definire l'ordinamento con cui i client *DOVREBBERO*
- mostrare le playlist agli utenti, o a definire quale playlist vada usata, se il client sceglie automaticamente
- senza proporrere all'utente. Il valore della priority è relativo alle altre source, non si riferisce ad altre
- radio. Valori di priority minori di zero indicano che la source non dovrebbe essere resa visibile all'utente
- in condizioni normali.
- * 0 o 1 oggetti ``shows``. Il campo ``src`` *DEVE* puntare ad una risorsa di formato _shows_ (vedi di
- seguito).
- * 0 o 1 ``feed``. Il campo ``src`` *DEVE* puntare ad una risorsa di tipo feed.
- ### Implementazione client
- Un client dovrebbe chiedere all'utente di fornire l'indirizzo base di un sito. Il manifest dovrebbe essere
- rintracciabile andando all'indirizzo ``radiomanifest.xml`` relativo all'indirizzo di un sito.
- Ad esempio, se l'utente inserisce "http://hosting.com/myradio/" il manifest *DEVE* essere cercato all'indirizzo
- "http://hosting.com/myradio/radiomanifest.xml"
- Quando un client vuole suonare lo streaming associato ad un radiomanifest, esso potrebbe voler mostrare
- all'utente la scelta tra le varie source, oppure decidere automaticamente.
- Se il client sceglie automaticamente:
- * *DEVE* rispettare l'ordinamento delle priority.
- * *DEVE* escludere le source con priority minore di zero.
- * Qualora la riproduzione della source dovesse avere problemi, *DOVREBBE* passare alla successiva
- * Se alcune source hanno uguale priority, *DOVREBBE* scegliere casualmente tra di esse
- Se il client fa scegliere l'utente:
- * *DEVE* rispettare l'ordinamento delle priority
- * *DOVREBBE* omettere le source con priority minore di zero.
- == Schedule
- The goal of the schedule is to express the typical weekly table that is commonly found in radio websites. It is an iCalendar file. Each show should be a distinct ``VEVENT``.
- The schedule *SHOULD* include at least events up until 1 week
- The schedule *SHOULD* use recurrency rule where appropriate, so that the user is informed of this.
- == Shows
- The goal of the shows file is to:
- * list shows
- * provide useful metadata for each show, such as:
- ** dedicated feed
- ** link to specialized page for the show
- Here is an example:
- <?xml version="1.0" encoding="UTF-8" ?>
- <shows>
- <show>
- <name>Learn to cook in C++</name>
- <website>http://radioexample.com/shows/learn-cook</website>
- <feed>http://radioexample.com/shows/learn-cook/feed</feed>
- <schedule>http://radioexample.com/shows/learn-cook.ics</schedule>
- </show>
- <show>
- <name>Uncensored information</name>
- <website>http://radioexample.com/shows/info</website>
- <feed>http://radioexample.com/shows/info/feed</feed>
- </show>
- </shows>
- (link:shows.xsd[Schema XSD])
- Only ``name`` is required. A schedule can point to an iCal resource. All entries in the calendar are assumed to
- be part of the show.
- === Relationship with schedule
- It's pretty clear that in many cases shows.xml and schedule.ics will benefit from being linked. How to do
- that?
- 1. If there is an ``X-SHOW-ID``, and it is the same as ``<name>``
- 2. If ``CATEGORIES`` include ``<name>``
- 3. If ``SUMMARY`` is the same as ``<name>``
- == Implementation details
- === HTTP Implementation
- Clients:
- - *MUST* provide an ``Accept`` header in every HTTP request. This will enable maximum flexibility in the
- future, allowing clients and servers to smoothly move to new file formats
- Servers:
- - *MUST* implement CORS adequately. Every file related to this specification must be retrievable by a browser
- on a different domain via a `GET`.
- == Casi d'uso
- === Player
- Supponiamo di voler realizzare un player di radio con feature avanzate, che sia però portabile su molte radio.
- Data una lista di URL di siti web, è possibile fare un player che:
- * supporti vari indirizzi di streaming in modo trasparente per l'utente
- * permetta all'utente di scegliere il tipo di streaming, ad esempio se la radio fornisce streaming di diversa
- qualità
- * possa dire all'utente informazioni utili sul palinsesto della radio che sta ascoltando
- * permetta di puntare allo storico, o di andare rapidamente alla pagina della trasmissione che sta
- ascoltando.
- Come capita spesso, questo può essere applicato anche alla scrittura di app che supportino molte radio, senza che però esse debbano essere limitate al solo streaming come è il caso attualmente (vedi le varie Transistor, RadioDroid, ecc.)
- === Radio automation
- Se un radio automation (della radio A) vuole importare contenuti da un'altra radio B, esso può facilmente
- fornire all'utente della radio A utili informazioni. Ad esempio, permette di vedere il palinsesto in forma
- grafica, selezionare uno show, vedere un'anteprima del feed corrispondente, quindi importarlo in una specifica
- fascia oraria.
- === radio-browser++
- https://www.radio-browser.info/ fornisce molte info utili su delle radio. Grazie a radio-manifest, sarebbe più semplice:
- * mantenere le informazioni in modo più semplice; finché una radio mantiene lo stesso sito web, può aggiornare la lista di url di streaming in modo automatico
- * più informazioni; radio-browser potrebbe includere le informazioni dettagliate disponibili tramite ``<schedule>`` e ``<shows>`` per fornire informazioni aggiuntive.
- === RadioDroid++
- RadioDroid is a fine Android app to listen to stream. We'd like to have an improved version of RadioDroid that
- also includes features that RadioManifest provide. See the _Player_ use case.
|