|
|
@@ -0,0 +1,168 @@
|
|
|
+= 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.
|
boyska
2 years ago