4735dba5de
if we ever need to apply some versioning later, we can do so introducing new tags, or specifying the version in other ways
214 lines
10 KiB
Text
214 lines
10 KiB
Text
= Radiomanifest specification
|
|
CiurmaPirata
|
|
:url-repo: https://git.lattuga.net/boyska/radiomanifest-spec
|
|
|
|
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
|
|
|
|
The syntax tries to be compatible with link:http://pyxml.sourceforge.net/topics/xbel/[XBEL], a bookmark
|
|
format. While this format has not seen extensive usage in the latest years, it's still valuable to reuse
|
|
someone else work instead of reinventing the wheel.
|
|
|
|
Here is an example:
|
|
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<xbel version="1.0"
|
|
xmlns:show="https://radiomanifest.degenerazione.xyz/shows/"
|
|
>
|
|
<bookmark href="http://radioexample.com/shows/learn-cook">
|
|
<title>Learn to cook in C++</title>
|
|
<info>
|
|
<metadata owner="https://radiomanifest.degenerazione.xyz/">
|
|
<show:name>Learn to cook in C++</show:name>
|
|
<show:id>learn-C++</show:id>
|
|
<show:description>A podcast about C++, templates, and nouvelle cuisine</show:description>
|
|
<show:website>http://radioexample.com/shows/learn-cook</show:website>
|
|
<show:feed>http://radioexample.com/shows/learn-cook/feed</show:feed>
|
|
<show:schedule>http://radioexample.com/shows/learn-cook.ics</show:schedule>
|
|
</metadata>
|
|
</info>
|
|
</bookmark>
|
|
<folder>
|
|
<title>Information</title>
|
|
<bookmark href="http://radioexample.com/shows/learn-cook">
|
|
<title>Uncensored information</title>
|
|
<info>
|
|
<metadata owner="https://radiomanifest.degenerazione.xyz/">
|
|
<show:name>Uncensored information</show:name>
|
|
<show:id>uncensored</show:id>
|
|
<show:description>News, news & more news</show:description>
|
|
<show:website>http://radioexample.com/shows/uncensored</show:website>
|
|
<show:feed type="application/rss+xml">http://radioexample.com/shows/uncensored/feed</show:feed>
|
|
<show:schedule type="text/calendar">http://radioexample.com/shows/uncensored.ics</show:schedule>
|
|
<show:schedule type="application/calendar+json">http://radioexample.com/shows/uncensored.json</show:schedule>
|
|
</metadata>
|
|
</info>
|
|
</bookmark>
|
|
</folder>
|
|
</xbel>
|
|
|
|
Only ``show:name`` is required, though parsers are invited to apply the Postel law and read the parent
|
|
``title`` element.
|
|
|
|
The ``type`` attribute is available for ``show:feed`` and ``show:schedule``; it defines the mime type of the
|
|
resource, so that in the future different formats can be used. Right now, the default is
|
|
``application/rss+xml`` for ``show:feed`` and ``text/calendar`` for ``show:schedule``.
|
|
|
|
``show:feed`` and ``show:schedule`` can be present multiple times; When this happens, the semantic is that
|
|
those files are equivalent, and can be considered different formats for the same data. The example shows
|
|
exactly this: here, the producer is providing the same calendar in both ICS and
|
|
link:https://tools.ietf.org/id/draft-kewisch-et-al-icalendar-in-json-00.html#RFC6321[jCal].
|
|
|
|
XBEL supports folders, and we want to be XBEL-compatible. However, the parser is free to flatten the folder
|
|
structure if they so prefer. In this case, they should use depth-first order when presenting the content to
|
|
the user. We encourage producers not to rely on the fact that the user will be able to use a tree-like
|
|
navigation.
|
|
|
|
|
|
=== 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? For every event in the schedule, apply this rules:
|
|
|
|
1. If the VEVENT has a ``X-SHOW-ID`` field, see if a show with the same ``<show:id>`` exists
|
|
2. If the VEVENT has a ``CATEGORIES`` field, see, for all categories, if a show has the same ``<show:id>``
|
|
3. If the VEVENT has a ``SUMMARY``, see if there is a show with the same ``<show:name>``
|
|
|
|
If any of this rule has a match, the event in the calendar belongs to that show.
|
|
|
|
== 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.
|
|
|
|
== Meta
|
|
|
|
This specification is versioned on {url-repo}[Git]
|