Presentation

RTDS stands for "Radio Tagging Data Schema". It's a standard JSON object that have to be provided by radios stations to applications like radio players. RTDS aims to standardize the way that tags are formated while streaming softwares like Shoutcast or Icecast still expose just a string containing the artist and the title.

Communication protocol

For radios

Computing your RTDS object may be a long task. It is recommended to compute it asynchronously from application calls. For example, at each song change, you will have to change and compute data inside your object, then keep it in a cache for every applications that will call for it after.

For applications

You have to provide radio producers a field where they will put the URL of their RTDS object. Then, just call the URL and parse the JSON data to get all data you need in your application.

Object description

First level objects

In order to make your RTDS object full, you need to specify many informations in it.

{
    "status": {…},
    "radio": {…},
    "streams": […],
    "tags": {…},
    "show": {…}
}

status

Mandatory object that describes the status of the request.

{
    "status": {
        "code": 200,
        "message": "Success.",
        "available_data": ["radio", "streams", "tags", "show"]
    }
}
Key Type Description
code integer Status code of the query.
message string Message associated to describe status.
available_data array of strings An array that contains every first level keys.

The status object allows you to describe how the request were completed. This is the only mandatory field while every other ones have not to be provided. This allows you to implement only "tags" for example, and also it will make it easy for RTDS to implement new services without requiring you to update your object structure at each update.

Available codes possibles and their meanings:

Code Meaning
200 Success. The object has been correctly retrieved.
301 Permanent redirection.
302 Temporary redirection.
401 Error. User not authenticated.
403 Error. Access not allowed.
404 Error. Data was not found.
503 Error. The server has encountered an error while retrieving data.
504 Error. The server did not respond.

See wikipedia for more HTTP codes.

radio

Description of your radio.

{
    "radio": {
        "name": "Utopic",
        "slogan": "Bonne Humeur Garantie",
        "description": "Écoute Utopic, et déguste une dose de bonheur enrobée d'énergie sur son coulis de légèreté.",
        "images": [
            {
                "type": "vectorial",
                "format": "free",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=svg"
            },
            {
                "type": "vectorial",
                "format": "square",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=svg"
            },
            {
                "type": "pixel",
                "format": "free",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=png&w=800",
                "width": 800,
                "height": 422
            },
            {
                "type": "pixel",
                "format": "square",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=png&w=800",
                "width": 800
            }
        ],
        "coordinates": {
            "type": "non-profit",
            "organisation": "Spicevent Association",
            "address": "…",
            "zip": "00000",
            "city": "…",
            "country": "France",
            "phones": [
                {
                    "type": "main",
                    "number": "+33979980118"
                }
            ]
        },
        "genres": ["Hits", "Feel good", "Top 40", "Variety"],
        "urls": {
            "web": "https://utopicradio.com/",
            "self": "https://utopicradio.com/tags",
            "social": [
                {
                    "type": "facebook",
                    "url": "https://facebook.com/utopicradio"
                },
                {
                    "type": "twitter",
                    "url": "https://twitter.com/utopicradio"
                }
            ],
            "extra": […]
        },
        "extra": […]
    }
}
Key Type Description
name string Name of the radio.
slogan string Your radio slogan.
description string A long description of your radio.
images array of images An array of images/logos/banners/… representing the radio. See images for more details.
coordinates object coordinates Coordinates of the head office of your radio. See coordinates for more details.
genres array of strings Main genres of your radio. See the list of genres below.
urls object url URLs associated to your radio. See url for more details.
extra array Extra data you can provide about your radio inside the RTDS object.

Non-exhaustive list of genres

Choose wisely:

#
2 tone
2-step garage
4-beat
4x4 garage
8-bit
A
acapella
acid
acid breaks
acid house
acid jazz
acid rock
acoustic music
acousticana
adult contemporary music
african popular music
african rumba
afrobeat
aleatoric music
alternative country
alternative dance
alternative hip hop
alternative metal
alternative rock
ambient
ambient house
ambient music
americana
anarcho punk
anti-folk
apala
ape haters
arab pop
arabesque
arabic pop
argentine rock
ars antiqua
ars nova
art punk
art rock
ashiq
asian american jazz
australian country music
australian hip hop
australian pub rock
austropop
avant-garde
avant-garde jazz
avant-garde metal
avant-garde music
axé
B
bac-bal
bachata
baggy
baila
baile funk
baisha xiyue
baithak gana
baião
bajourou
bakersfield sound
bakou
bakshy
bal-musette
balakadri
balinese gamelan
balkan pop
ballad
ballata
ballet
bamboo band
bambuco
banda
bangsawan
bantowbol
barbershop music
barndance
baroque
baroque music
baroque pop
bass music
batcave
batucada
batuco
batá-rumba
beach music
beat
beatboxing
beautiful music
bebop
beiguan
bel canto
bend-skin
benga
berlin school of electronic music
bhajan
bhangra
bhangra-wine
bhangragga
bhangramuffin
big band
big band music
big beat
biguine
bihu
bikutsi
biomusic
bitcore
bitpop
black metal
blackened death metal
blue-eyed soul
bluegrass
blues
blues ballad
blues-rock
boogie
boogie woogie
boogie-woogie
bossa nova
brass band
brazilian funk
brazilian jazz
breakbeat
breakbeat hardcore
breakcore
breton music
brill building pop
britfunk
british blues
british invasion
britpop
broken beat
brown-eyed soul
brukdown
brutal death metal
bubblegum dance
bubblegum pop
bulerias
bumba-meu-boi
bunraku
burger-highlife
burgundian school
byzantine chant
C
ca din tulnic
ca pe lunca
ca trù
cabaret
cadence
cadence rampa
cadence-lypso
café-aman
cai luong
cajun music
cakewalk
calenda
calentanos
calgia
calypso
calypso jazz
calypso-style baila
campursari
canatronic
candombe
canon
canrock
cantata
cante chico
cante jondo
canterbury scene
cantiga
cantique
cantiñas
canto livre
canto nuevo
canto popular
cantopop
canzone napoletana
cape jazz
capoeira music
caracoles
carceleras
cardas
cardiowave
carimbó
cariso
carnatic music
carol
cartageneras
cassette culture
casséy-co
cavacha
caveman
caña
celempungan
cello rock
celtic
celtic fusion
celtic metal
celtic punk
celtic reggae
celtic rock
cha-cha-cha
chakacha
chalga
chamamé
chamber jazz
chamber music
chamber pop
champeta
changuí
chanson
chant
charanga
charanga-vallenata
charikawi
chastushki
chau van
chemical breaks
chicago blues
chicago house
chicago soul
chicano rap
chicha
chicken scratch
children's music
chillout
chillwave
chimurenga
chinese music
chinese pop
chinese rock
chip music
cho-kantrum
chongak
chopera
chorinho
choro
chouval bwa
chowtal
christian alternative
christian black metal
christian electronic music
christian hardcore
christian hip hop
christian industrial
christian metal
christian music
christian punk
christian r&b
christian rock
christian ska
christmas carol
christmas music
chumba
chut-kai-pang
chutney
chutney soca
chutney-bhangra
chutney-hip hop
chutney-soca
chylandyk
chzalni
chèo
cigányzene
classic
classic country
classic female blues
classic rock
classical
classical music
classical music era
clicks n cuts
close harmony
club music
cocobale
coimbra fado
coladeira
colombianas
combined rhythm
comedy
comedy rap
comedy rock
comic opera
comparsa
compas direct
compas meringue
concert overture
concerto
concerto grosso
congo
conjunto
contemporary christian
contemporary christian music
contemporary classical
contemporary r&b
contonbley
contradanza
cool jazz
corrido
corsican polyphonic song
cothoza mfana
country
country blues
country gospel
country music
country pop
country r&b
country rock
country-rap
countrypolitan
couple de sonneurs
coupé-décalé
cowpunk
cretan music
crossover jazz
crossover music
crossover thrash
crossover thrash metal
crunk
crunk&b
crunkcore
crust punk
csárdás
cuarteto
cuban rumba
cuddlecore
cueca
cumbia
cumbia villera
cybergrind
D
dabka
dadra
daina
dalauna
dance
dance music
dance-pop
dance-punk
dance-rock
dancehall
dangdut
danger music
dansband
danza
danzón
dark ambient
dark cabaret
dark pop
darkcore
darkstep
darkwave
de ascultat la servici
de codru
de dragoste
de jale
de pahar
death industrial
death metal
death rock
death/doom
deathcore
deathgrind
deathrock
deep funk
deep house
deep soul
degung
delta blues
dementia
desert rock
desi
detroit blues
detroit techno
dhamar
dhimotiká
dhrupad
dhun
digital hardcore
dirge
dirty dutch
dirty rap
dirty rap/pornocore
dirty south
disco
disco house
disco polo
disney
disney hardcore
disney pop
diva house
divine rock
dixieland
dixieland jazz
djambadon
djent
dodompa
doina
dombola
dondang sayang
donegal fiddle tradition
dongjing
doo wop
doom metal
doomcore
downtempo
drag
dream pop
drone doom
drone metal
drone music
dronology
drum and bass
dub
dub house
dubanguthu
dubstep
dubtronica
dunedin sound
dunun
dutch jazz
décima
E
early music
east coast blues
east coast hip hop
easy listening
electric blues
electric folk
electro
electro backbeat
electro hop
electro house
electro punk
electro-industrial
electro-swing
electroclash
electrofunk
electronic
electronic art music
electronic body music
electronic dance
electronic luk thung
electronic music
electronic rock
electronica
electropop
elevator music
emo
emo pop
emo rap
emocore
emotronic
enka
eremwu eu
ethereal pop
ethereal wave
euro
euro disco
eurobeat
eurodance
europop
eurotrance
eurourban
exotica
experimental music
experimental noise
experimental pop
experimental rock
extreme metal
ezengileer
F
fado
falak
fandango
farruca
fife and drum blues
filk
film score
filmi
filmi-ghazal
finger-style
fjatpangarri
flamenco
flamenco rumba
flower power
foaie verde
fofa
folk hop
folk metal
folk music
folk pop
folk punk
folk rock
folktronica
forró
franco-country
freak-folk
freakbeat
free improvisation
free jazz
free music
freestyle
freestyle house
freetekno
french pop
frenchcore
frevo
fricote
fuji
fuji music
fulia
full on
funaná
funeral doom
funk
funk metal
funk rock
funkcore
funky house
furniture music
fusion jazz
G
g-funk
gaana
gabba
gabber
gagaku
gaikyoku
gaita
galant
gamad
gambang kromong
gamelan
gamelan angklung
gamelan bang
gamelan bebonangan
gamelan buh
gamelan degung
gamelan gede
gamelan kebyar
gamelan salendro
gamelan selunding
gamelan semar pegulingan
gamewave
gammeldans
gandrung
gangsta rap
gar
garage rock
garrotin
gavotte
gelugpa chanting
gender wayang
gending
german folk music
gharbi
gharnati
ghazal
ghazal-song
ghetto house
ghettotech
girl group
glam metal
glam punk
glam rock
glitch
gnawa
go-go
goa
goa trance
gong-chime music
goombay
goregrind
goshu ondo
gospel music
gothic metal
gothic rock
granadinas
grebo
gregorian chant
grime
grindcore
groove metal
group sounds
grunge
grupera
guaguanbo
guajira
guasca
guitarra baiana
guitarradas
gumbe
gunchei
gunka
guoyue
gwo ka
gwo ka moderne
gypsy jazz
gypsy punk
gypsybilly
gyu ke
H
habanera
hajnali
hakka
halling
hambo
hands up
hapa haole
happy hardcore
haqibah
hard
hard bop
hard house
hard rock
hard trance
hardcore hip hop
hardcore metal
hardcore punk
hardcore techno
hardstyle
harepa
harmonica blues
hasaposérviko
heart attack
heartland rock
heavy beat
heavy metal
hesher
hi-nrg
highlands
highlife
highlife fusion
hillybilly music
hindustani classical music
hip hop
hip hop & rap
hip hop soul
hip house
hiplife
hiragasy
hiva usu
hong kong and cantonese pop
hong kong english pop
honky tonk
honkyoku
hora lunga
hornpipe
horror punk
horrorcore
horrorcore rap
house
house music
hua'er
huasteco
huayno
hula
humor
humppa
hunguhungu
hyangak
hymn
hyphy
hát chau van
hát chèo
hát cãi luong
hát tuồng
I
ibiza music
icaro
idm
igbo music
ijexá
ilahije
illbient
impressionist music
improvisational
incidental music
indian pop
indie folk
indie music
indie pop
indie rock
indietronica
indo jazz
indo rock
indonesian pop
indoyíftika
industrial death metal
industrial hip-hop
industrial metal
industrial music
industrial musical
industrial rock
instrumental rock
intelligent dance music
international latin
inuit music
iranian pop
irish folk
irish rebel music
iscathamiya
isicathamiya
isikhwela jo
island
isolationist
italo dance
italo disco
italo house
itsmeños
izvorna bosanska muzika
J
j'ouvert
j-fusion
j-pop
j-rock
jaipongan
jaliscienses
jam band
jam rock
jamana kura
jamrieng samai
jangle pop
japanese pop
jarana
jariang
jarochos
jawaiian
jazz
jazz blues
jazz fusion
jazz metal
jazz rap
jazz-funk
jazz-rock
jegog
jenkka
jesus music
jibaro
jig
jig punk
jing ping
jingle
jit
jitterbug
jive
joged
joged bumbung
joik
jonnycore
joropo
jota
jtek
jug band
jujitsu
juju
juke joint blues
jump blues
jumpstyle
jungle
junkanoo
juré
jùjú
K
k-pop
kaba
kabuki
kachāshī
kadans
kagok
kagyupa chanting
kaiso
kalamatianó
kalattuut
kalinda
kamba pop
kan ha diskan
kansas city blues
kantrum
kantádhes
kargyraa
karma
kaseko
katajjaq
kawachi ondo
kayōkyoku
ke-kwe
kebyar
kecak
kecapi suling
kertok
khaleeji
khap
khelimaski djili
khene
khoomei
khorovodi
khplam wai
khrung sai
khyal
kilapanda
kinko
kirtan
kiwi rock
kizomba
klape
klasik
klezmer
kliningan
kléftiko
kochare
kolomyjka
komagaku
kompa
konpa
korean pop
koumpaneia
kpanlogo
krakowiak
krautrock
kriti
kroncong
krump
krzesany
kuduro
kulintang
kulning
kumina
kun-borrk
kundere
kundiman
kussundé
kutumba wake
kveding
kvæði
kwaito
kwassa kwassa
kwela
käng
kélé
kĩkũyũ pop
L
la la
latin american
latin jazz
latin pop
latin rap
lavway
laïko
laïkó
le leagan
legényes
lelio
letkajenkka
levenslied
lhamo
lieder
light music
light rock
likanos
liquid drum&bass
liquid funk
liquindi
llanera
llanto
lo-fi
lo-fi music
loki djili
long-song
louisiana blues
louisiana swamp pop
lounge music
lovers rock
lowercase
lubbock sound
lucknavi thumri
luhya omutibo
luk grung
lullaby
lundu
lundum
M
m-base
madchester
madrigal
mafioso rap
maglaal
magnificat
mahori
mainstream jazz
makossa
makossa-soukous
malagueñas
malawian jazz
malhun
maloya
maluf
maluka
mambo
manaschi
mandarin pop
manding swing
mango
mangue bit
mangulina
manikay
manila sound
manouche
manzuma
mapouka
mapouka-serré
marabi
maracatu
marga
mariachi
marimba
marinera
marrabenta
martial industrial
martinetes
maskanda
mass
matamuerte
math rock
mathcore
matt bello
maxixe
mazurka
mbalax
mbaqanga
mbube
mbumba
medh
medieval folk rock
medieval metal
medieval music
meditation
mejorana
melhoun
melhûn
melodic black metal
melodic death metal
melodic hardcore
melodic metalcore
melodic music
melodic trance
memphis blues
memphis rap
memphis soul
mento
merengue
merengue típico moderno
merengue-bomba
meringue
merseybeat
metal
metalcore
metallic hardcore
mexican pop
mexican rock
mexican son
meykhana
mezwed
miami bass
microhouse
middle of the road
midwest hip hop
milonga
min'yo
mineras
mini compas
mini-jazz
minimal techno
minimalist music
minimalist trance
minneapolis sound
minstrel show
minuet
mirolóyia
modal jazz
modern classical
modern classical music
modern laika
modern rock
modinha
mohabelo
montuno
monumental dance
mor lam
mor lam sing
morna
motorpop
motown
mozambique
mpb
mugam
multicultural
murga
musette
museve
mushroom jazz
music drama
music hall
musiqi-e assil
musique concrète
mutuashi
muwashshah
muzak
méringue
música campesina
música criolla
música de la interior
música llanera
música nordestina
música popular brasileira
música tropical
N
nagauta
nakasi
nangma
nanguan
narcocorrido
nardcore
narodna muzika
nasheed
nashville sound
nashville sound/countrypolitan
national socialist black metal
naturalismo
nederpop
neo soul
neo-classical metal
neo-medieval
neo-prog
neo-psychedelia
neoclassical
neoclassical music
neofolk
neotraditional country
nerdcore
neue deutsche härte
neue deutsche welle
new age music
new beat
new instrumental
new jack swing
new orleans blues
new orleans jazz
new pop
new prog
new rave
new romantic
new school hip hop
new taiwanese song
new wave
new wave of british heavy metal
new wave of new wave
new weird america
new york blues
new york house
newgrass
nganja
nightcore
nintendocore
nisiótika
no wave
noh
noise music
noise pop
noise rock
nongak
norae undong
nordic folk dance music
nordic folk music
nortec
norteño
northern soul
nota
nu breaks
nu jazz
nu metal
nu soul
nueva canción
nyatiti
néo kýma
O
obscuro
oi!
old school hip hop
old-time
oldies
olonkho
oltului
ondo
opera
operatic pop
oratorio
orchestra
orchestral
organ trio
organic ambient
organum
orgel
oriental metal
ottava rima
outlaw country
outsider music
P
p-funk
pagan metal
pagan rock
pagode
paisley underground
palm wine
palm-wine
pambiche
panambih
panchai baja
panchavadyam
pansori
paranda
parang
parody
parranda
partido alto
pasillo
patriotic
peace punk
pelimanni music
petenera
peyote song
philadelphia soul
piano blues
piano rock
piedmont blues
pimba
pinoy pop
pinoy rock
pinpeat orchestra
piphat
piyyutim
plainchant
plena
pleng phua cheewit
pleng thai sakorn
political hip hop
polka
polo
polonaise
pols
polska
pong lang
pop
pop folk
pop music
pop punk
pop rap
pop rock
pop sunda
pornocore
porro
post disco
post-britpop
post-disco
post-grunge
post-hardcore
post-industrial
post-metal
post-minimalism
post-punk
post-rock
post-romanticism
pow-wow
power electronics
power metal
power noise
power pop
powerviolence
ppongtchak
praise song
program symphony
progressive bluegrass
progressive country
progressive death metal
progressive electronic
progressive electronic music
progressive folk
progressive folk music
progressive house
progressive metal
progressive rock
progressive trance
protopunk
psych folk
psychedelic music
psychedelic pop
psychedelic rock
psychedelic trance
psychobilly
punk blues
punk cabaret
punk jazz
punk rock
punta
punta rock
Q
qasidah
qasidah modern
qawwali
quadrille
quan ho
queercore
quiet storm
R
rada
raga
raga rock
ragga
ragga jungle
raggamuffin
ragtime
rai
rake-and-scrape
ramkbach
ramvong
ranchera
rap
rap metal
rap rock
rapcore
rara
rare groove
rasiya
rave
raw rock
raï
rebetiko
red dirt
reel
reggae
reggae 110
reggae bultrón
reggae en español
reggae fusion
reggae highlife
reggaefusion
reggaeton
rekilaulu
relax music
religious
rembetiko
renaissance music
requiem
rhapsody
rhyming spiritual
rhythm & blues
rhythm and blues
ricercar
riot grrrl
rock
rock and roll
rock en español
rock opera
rockabilly
rocksteady
rococo
romantic flow
romantic period in music
rondeaux
ronggeng
roots reggae
roots rock
roots rock reggae
rumba
russian pop
rímur
S
sabar
sacred harp
sacred music
sadcore
saibara
sakara
salegy
salsa
salsa erotica
salsa romantica
saltarello
samba
samba-canção
samba-reggae
samba-rock
sambai
sanjo
sato kagura
sawt
saya
scat
schlager
schottisch
schranz
scottish baroque music
screamo
scrumpy and western
sea shanty
sean nós
second viennese school
sega music
seggae
seis
semba
sephardic music
serialism
set dance
sevdalinka
sevillana
shabab
shabad
shalako
shan'ge
shango
shape note
shibuya-kei
shidaiqu
shima uta
shock rock
shoegaze
shoegazer
shoka
shomyo
show tune
sica
siguiriyas
silat
sinawi
situational
ska
ska punk
skacore
skald
skate punk
skiffle
slack-key guitar
slide
slowcore
sludge metal
slängpolska
smooth jazz
soca
soft rock
son
son montuno
son-batá
sonata
songo
songo-salsa
sophisti-pop
soukous
soul
soul blues
soul jazz
soul music
southern gospel
southern harmony
southern hip hop
southern metal
southern rock
southern soul
space age pop
space music
space rock
spectralism
speed garage
speed metal
speedcore
spirituals
spouge
sprechgesang
square dance
squee
st. louis blues
stand-up
steelband
stoner metal
stoner rock
straight edge
strathspeys
stride
string
string quartet
sufi music
suite
sunshine pop
suomirock
super eurobeat
surf ballad
surf instrumental
surf music
surf pop
surf rock
swamp blues
swamp pop
swamp rock
swing
swing music
swingbeat
sygyt
symphonic
symphonic black metal
symphonic metal
symphonic poem
symphonic rock
symphony
synthpop
synthpunk
T
t'ong guitar
taarab
tai tu
taiwanese pop
tala
talempong
tambu
tamburitza
tamil christian keerthanai
tango
tanguk
tappa
tarana
tarantella
taranto
tech
tech house
tech trance
technical death metal
technical metal
techno
technoid
technopop
techstep
techtonik
teen pop
tejano
tejano music
tekno
tembang sunda
texas blues
thai pop
thillana
thrash metal
thrashcore
thumri
tibetan pop
tiento
timbila
tin pan alley
tinga
tinku
toeshey
togaku
trad jazz
traditional bluegrass
traditional pop music
trallalero
trance
tribal house
trikitixa
trip hop
trip rock
trip-hop
tropicalia
tropicalismo
tropipop
truck-driving country
tumba
turbo-folk
turkish music
turkish pop
turntablism
tuvan throat-singing
twee pop
twist
two tone
táncház
U
uk garage
uk pub rock
unblack metal
underground music
uplifting
uplifting trance
urban cowboy
urban folk
urban jazz
V
vallenato
vaudeville
venezuela
verbunkos
verismo
viking metal
villanella
virelai
vispop
visual kei
visual music
vocal
vocal house
vocal jazz
vocal music
volksmusik
W
waila
waltz
wangga
warabe uta
wassoulou
weld
were music
west coast hip hop
west coast jazz
western
western blues
western swing
witch house
wizard rock
women's music
wong shadow
wonky pop
wood
work song
world fusion
world fusion music
world music
worldbeat
X
xhosa music
xoomii
Y
yo-pop
yodeling
yukar
yé-yé
Z
zajal
zapin
zarzuela
zeibekiko
zeuhl
ziglibithy
zouglou
zouk
zouk chouv
zouklove
zulu music
zydeco

streams

This field is an array of streams objects. A stream object provides URL to listen a radio and some informations about it.

{
    "streams": [
        {
            "type": "main",
            "format": "mp3",
            "quality": 128,
            "channels": 2,
            "url": "https://utopicradio.com/listen"
        },
        …
    ]
}
Key Type Description
type string Describes wether the stream is the main stream to use or other ones. See the list of types below.
format string The format of the stream. See the list of formats below.
quality integer The quality of the stream, in kbps.
channels integer The number of channels of the stream.
url string URL to the stream.

List of stream types

Type Meaning
main This is your main URL to listen to your radio
redirect HTTP Redirected URL to listen to your stream
proxy URL of your stream, proxified
other Other URLs that point to your stream

You need to have at least one stream with the "main" type.

List of formats

Format Key
MPEG Layer 3 mp3
Advanced Audio Coding aac
Ogg Vorbis ogg

tags

The tags object contains informations about the song currently played.

{
    "tags": {
        "artists": [
            "Madeon", "Passion Pit"
        ],
        "title": "Pay No Mind",
        "album": "Adventure (Deluxe)",
        "year": 2015,
        "cover": {
            "url": "https://i.scdn.co/image/41fa5c07121f5b6cc7d0eac34933ed0722c7dc1c",
            "width": 640,
            "height": 640
        },
        "genres": ["electronic", "pop"],
        "categories": ["Musiques", "Nouveaut\u00e9s"],
        "length": 249.89565343,
        "remaining": 92.54773021,
        "urls": {
            "buy": ["…"],
            "stream": ["…"],
            "extra": […]
        },
        "extra": […],
        "previous": {
            …
        },
        "next": {
            …
        }
    }
}
Key Type Description
artists array of strings The list of all artists of the song. Better to separate artists in an array, so you can avoid separators like "ft.", "feat.", ", ", or " - "
title string The title of the song.
album string The album the song is on. Avoid compilation albums and prefer original albums.
year integer The year of release of the song.
cover object The cover art of the song. url: the cover art URL - width: the width of the picture - height: the height of the picture.
genres array of strings The main genres of the song. See the list of genres above.
categories array of strings The main categories of the song. This field is different from "genres" in that "categories" represent the categories you have affected the song in, in your song database. For example, it can be "Hits", "Golds", "Newest ones", "High rotation", etc.
length float The total length of the song. If your radio automation software have the ability to put mix points on songs, put the actual length of the song playable in your software (excluding sound before start point and sound after end point).
remaining float The time remaining before the end of the song. If your radio automation software have the ability to put mix points on songs, compute the remaining time before the end point of your song and not the end of the file. This property cannot be stored in cache, you will have to recompute it each time an app need your RTDS object (this can make its generation a heavy task).
urls object url URLs associated to the song. See url for more details.
extra array Extra data you can provide about the song.
previous object tags Data of the previous streamed song. Remaining time is not necessary inside this object.
next object tags Data of the next streamed song. Remaining time is not necessary inside this object.

show

This object give informations about the show streamed.

{
    "show": {
        "name": "L'Afterwork",
        "description": "Dure journée de boulot ? Écoutez Kris sur Utopic dans l'Afterwork, tous les jours de 17h à 19h pour retrouver le sourire !",
        "recurrences": [
            {
                "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
                "dates": {
                    "start": "2017/08/28",
                    "end": "2017/06/29"
                },
                "hours": {
                    "start": "17:00",
                    "end": "19:00"
                }
            }
        ],
        "contributors": [
            {
                "name": "Kris",
                "role": "main",
                "images": [
                    {
                        "type": "pixel",
                        "format": "free",
                        "url": "https://…",
                        "width": 800,
                        "height": 600
                    }
                ],
                "urls": {
                    "social": [
                        {
                            "type": "twitter",
                            "url": "https://twitter.com/christophermh44"
                        }
                    ]
                }
            }
        ],
        "images": [
            {
                "type": "vectorial",
                "format": "free",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=svg"
            },
            {
                "type": "vectorial",
                "format": "square",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=svg"
            },
            {
                "type": "pixel",
                "format": "free",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=png&w=800",
                "width": 800,
                "height": 422
            },
            {
                "type": "pixel",
                "format": "square",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=png&w=800",
                "width": 800
            }
        ],
        "urls": {
            "web": "https://utopicradio.com/emissions/l-afterwork",
            "social": [
                {
                    "type": "twitter",
                    "url": "https://twitter.com/christophermh44"
                }
            ],
            "extra": […]
        },
        "phones": [
            {
                "type": "main",
                "number": "+33979980118"
            }
        ]
    }
}
Key Type Description
name string Name of the show.
description string A short description of the show.
recurrences array of recurrences List of all dates and times the show is on air. See recurrence for more details.
contributors array of contributors List of contributors who animate the show. See contributors for more details.
images array of images An array of images/logos/banners/… representing the show. See images for more details.
urls object url URLs associated to the show. See url for more details.
phones array of object phones List of phone numbers to contact the show. See phone for more details.
extra array Extra data you can provide about the show.

Shared objects

Image

Image arrays represent group of images. Many informations describing the picture are provided to help applications choosing the right image by selecting them by arbitrary criteria.

{
    "images": [
        {
            "type": "pixel",
            "format": "free",
            "transparency": true,
            "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=png&w=800",
            "width": 800,
            "height": 422
        }
    ]
}
Key Type Description
type string Describes the type of the image provided. Can be "pixel" (typically PNG, JPG, …) or "vectorial" (SVG, …).
format string Describes the format of the image provided. "free" indicates that there is no dimension constraints. This value can also be a ratio ("2.39:1" or "16:9" for example). If the ratio is "1:1", the value can be "square".
transparency boolean Indicates wether the image contains an alpha layer or not.
url string URL to the actual image.
width integer Width of the image. Not required for vectorial pictures.
height integer Height of the image. Not required for vectorial pictures and square images.

Coordinates

Informations like social reason, postal address, phone numbers, …

{
    "coordinates": {
        "type": "non-profit",
        "organisation": "Spicevent Association",
        "address": "…",
        "zip": "00000",
        "city": "…",
        "country": "France",
        "phones": [
            {
                "type": "main",
                "number": "+33979980118"
            }
        ]
    }
}
Key Type Description
type string The type of organisation. "company", "non-profit", "group", "private" are valid values.
organisation string The name of your organisation.
address string Head quarter address.
zip string Head quarter Zip code.
city string Head quarter city.
country string Head quarter country.
phones array of phones Phone numbers to join your organisation. See phone for more information.

Phone

Phones fields are always arrays of phone objects to allow multiple phones to be set.

{
    "phones": [
        {
            "type": "main",
            "number": "+33979980118"
        }
    ]
}
Key Type Description
type string The type of phone number. See the list of types below.
number string The phone number.
List of phone types
Type Meaning
main Main phone number
direct Direct line
messaging Voice messaging
assistant Multiple-choice call
standard Line to your switchboard
personal Personal line
professionnal Professionnal line
fax Fax number

URLs

URLs objects can describe many URLs to your website and external services related.

{
    "urls": {
        "web": "https://utopicradio.com/",
        "self": "https://utopicradio.com/tags",
        "social": [
            {
                "type": "facebook",
                "url": "https://facebook.com/utopicradio"
            },
            {
                "type": "twitter",
                "url": "https://twitter.com/utopicradio"
            }
        ],
        "extra": [
            {
                "type": "participer",
                "description": "Participer aux émissions en direct sur Utopic",
                "url": "https://utopicradio.com/participer"
            },
            …
        ]
    }
}
Key Type Description
self string Canonical URL to call your API that provides your RTDS object.
web string Canonical URL of your main website page.
parent string Canonical URL of the organization that produce the radio.
player string URL to your player
listen string URL to your listen instructions page
legal_notice string URL to your legal notice
contact string URL to your contact page
social array Many URLs to your social networks profiles. Provide for each object in this array the type (valid values are "facebook", "twitter", "google-plus", "instagram", "linkedin", "viadeo", "youtube", "reddit", "pinterest", "discord", "other") and the url.
buy array URLs to buy the music. Provide for each object in this array the type (valid values are "itunes", "amazon", "other") and the url.
stream array URLs to listen to the music online. Provide for each object in this array the type (valid values are "itunes", "spotify", "youtube", "apple-music", "rhapsody", "deezer", "google-play", "tidal", "i-heart-radio", "shazam", "groove", "pandora", "vivo") and the url.
extra array Other URLs you want to provide. Provide for each object in this array an arbitrary type, the url and a description.

Recurrence

A recurrence object describes a time slot.

{
    "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "dates": {
        "start": "2017/08/28",
        "end": "2017/06/29"
    },
    "hours": {
        "start": "17:00",
        "end": "19:00"
    }
}
Key Type Description
days array of strings Days of week (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday are valid values).
dates object Describe the start date and the end date. End date is not required. If you do not provide an end date, it will implicitly be means that the end date is the same as the start date. The format of a date is yyyy/mm/dd
hours object Describe the start hour and the end hour. The format of an hour is hh:mm. You can also set an empty string for both start and end, thus it means that the recurrence last all day.

Contributor

A contributor object describes people like a show presenter, a producer, etc.

{
    "name": "Kris",
    "roles": ["main"],
    "images": [
        {
            "type": "pixel",
            "format": "free",
            "url": "https://…",
            "width": 800,
            "height": 600
        }
    ],
    "urls": {
        "social": [
            {
                "type": "twitter",
                "url": "https://twitter.com/christophermh44"
            }
        ]
    }
}
Key Type Description
name string Name of the contributor
role array of strings Roles of the contributor. Valid values are "main", "presenter", "director", "producer", "community-manager", "operator", "webmaster", "other".
images array of images Pictures that represents the contributor. See images for more details.
urls object url URLs to public profiles of the contributor. See url for more details.

Full RTDS object example

{
    "status": {
        "code": 200,
        "message": "Success.",
        "available_data": ["radio", "streams", "tags", "show"]
    },
    "radio": {
        "name": "Utopic",
        "slogan": "Bonne Humeur Garantie",
        "description": "Écoute Utopic, et déguste une dose de bonheur enrobée d'énergie sur son coulis de légèreté.",
        "images": [
            {
                "type": "vectorial",
                "format": "free",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=svg"
            },
            {
                "type": "vectorial",
                "format": "square",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=svg"
            },
            {
                "type": "pixel",
                "format": "free",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=png&w=800",
                "width": 800,
                "height": 422
            },
            {
                "type": "pixel",
                "format": "square",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=png&w=800",
                "width": 800
            }
        ],
        "coordinates": {
            "type": "non-profit",
            "organisation": "Spicevent Association",
            "address": "51 bis Chemin de Nantes",
            "zip": "44140",
            "city": "Geneston",
            "country": "France",
            "phones": [
                {
                    "type": "main",
                    "number": "+33979980118"
                }
            ]
        },
        "genres": ["Hits", "Feel good", "Top 40", "Variety"],
        "urls": {
            "web": "https://utopicradio.com/",
            "self": "https://utopicradio.com/tags",
            "social": [
                {
                    "type": "facebook",
                    "url": "https://facebook.com/utopicradio"
                },
                {
                    "type": "twitter",
                    "url": "https://twitter.com/utopicradio"
                }
            ],
            "extra": […]
        },
        "extra": […]
    },
    "streams": [
        {
            "type": "main",
            "format": "mp3",
            "quality": 128,
            "channels": 2,
            "url": "https://str2.openstream.co/394"
        },
        {
            "type": "redirect",
            "format": "mp3",
            "quality": 128,
            "channels": 2,
            "url": "https://utopicradio.com/listen"
        },
        {
            "type": "proxy",
            "format": "mp3",
            "quality": 128,
            "channels": 2,
            "url": "https://utopicradio.com/listen-relay"
        }
    ],
    "tags": {
        "artists": [
            "Madeon", "Passion Pit"
        ],
        "title": "Pay No Mind",
        "album": "Adventure (Deluxe)",
        "year": 2015,
        "cover": {
            "url": "https://i.scdn.co/image/41fa5c07121f5b6cc7d0eac34933ed0722c7dc1c",
            "width": 640,
            "height": 640
        },
        "genres": ["electronic", "pop"],
        "categories": ["Musiques", "Nouveaut\u00e9s"],
        "remaining": 92.54773021,
        "length": 249.89565343,
        "urls": {
            "buy": "",
            "stream": "",
            "extra": […]
        },
        "extra": […],
        "previous": {
            "artists": [
                "Madeon", "Passion Pit"
            ],
            "title": "Pay No Mind",
            "album": "Adventure (Deluxe)",
            "year": 2015,
            "cover": {
                "url": "https://i.scdn.co/image/41fa5c07121f5b6cc7d0eac34933ed0722c7dc1c",
                "width": 640,
                "height": 640
            },
            "genres": ["electronic", "pop"],
            "categories": ["Musiques", "Nouveaut\u00e9s"],
            "length": 249.89565343,
            "urls": {
                "buy": "",
                "stream": "",
                "social": […],
                "extra": […]
            },
            "extra": […]
        },
        "next": {
            "artists": [
                "Madeon", "Passion Pit"
            ],
            "title": "Pay No Mind",
            "album": "Adventure (Deluxe)",
            "year": 2015,
            "cover": {
                "url": "https://i.scdn.co/image/41fa5c07121f5b6cc7d0eac34933ed0722c7dc1c",
                "width": 640,
                "height": 640
            },
            "genres": ["electronic", "pop"],
            "categories": ["Musiques", "Nouveaut\u00e9s"],
            "length": 249.89565343,
            "urls": {
                "buy": "",
                "stream": "",
                "extra": […]
            },
            "extra": […]
        }
    },
    "show": {
        "name": "L'Afterwork",
        "description": "Dure journée de boulot ? Écoutez Kris sur Utopic dans l'Afterwork, tous les jours de 17h à 19h pour retrouver le sourire !",
        "occurrences": [
            {
                "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
                "dates": {
                    "start": "2017/08/28",
                    "end": "2017/06/29"
                },
                "hours": {
                    "start": "17:00",
                    "end": "19:00"
                }
            },
            …
        ],
        "contributors": [
            {
                "name": "Kris",
                "roles": ["main"],
                "images": [
                    {
                        "type": "pixel",
                        "format": "free",
                        "url": "https://…",
                        "width": 800,
                        "height": 600
                    }
                ],
                "urls": {
                    "social": [
                        {
                            "type": "twitter",
                            "url": "https://twitter.com/christophermh44"
                        }
                    ]
                }
            }
        ],
        "images": [
            {
                "type": "vectorial",
                "format": "free",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=svg"
            },
            {
                "type": "vectorial",
                "format": "square",
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=svg"
            },
            {
                "type": "pixel",
                "format": "free",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.maxi&t=png&w=800",
                "width": 800,
                "height": 422
            },
            {
                "type": "pixel",
                "format": "square",
                "transparency": true,
                "url": "https://dev.utopicradio.com/tools/vecto/svg-proxy.php?f=utopic.logo.mini&t=png&w=800",
                "width": 800
            }
        ],
        "urls": {
            "web": "https://utopicradio.com/emissions/l-afterwork",
            "social": [
                {
                    "type": "twitter",
                    "url": "https://twitter.com/christophermh44"
                }
            ],
            "extra": [
                {
                    "type": "participer",
                    "description": "Participer aux émissions en direct sur Utopic",
                    "url": "https://utopicradio.com/participer"
                },
                …
            ]
        },
        "phones": [
            {
                "type": "main",
                "number": "+33979980118"
            }
        ]
    }
}

PHP Implementation

While this part is being written, take a look to the test folder where you will find some examples easy to understand.