/usr/share/doc/liquidsoap/html/flows.html is in liquidsoap 1.1.1-6ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | <?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML \
1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type" />
<title>Liquidsoap :: Flows</title>
<link href="css/style.css" type="text/css" rel="stylesheet" />
</head>
<body>
<div id="wrapper">
<div id="header">
<div id="logo">
<h1>Liquidsoap</h1>
<h2>audio stream generation</h2>
</div>
<div>
<ul id="menu">
<li id="menu-about">
<a href="index.html">about</a></li>
<li id="menu-doc-index">
<a href="documentation.html">documentation</a></li>
<li id="menu-doc-api">
<a href="reference.html">API</a></li>
<li id="menu-doc-snippets">
<a href="scripts/index.html">snippets</a></li>
<li id="menu-developers">
<a href="https://github.com/savonet/liquidsoap/issues">developers</a></li>
</ul>
</div>
</div>
<div id="content"><div>
<h3>Flows</h3>
<p>
We maintain a
<a href="http://flows.liquidsoap.fm/" target="_blank">webpage of streams generated by Liquidsoap</a>.
In order to register your radio on this page, a simple
operator called <code>register_flow</code> is provided. If your stream is called <code>stream</code>,
just wrap it as follows before outputting it:
</p>
<pre class="syntax ">stream = register_flow(
radio="My radio",
website="http://my.web.site/",
description="The sound of my computer",
genre="reggae",
user="foo",
password="bar",
streams=[("mp3/128k","http://my.web.site/stream")],
stream)
</pre>
<p>
Most parameters are pretty explicit: <code>radio</code> is the name of the radio,
<code>website</code> is the url of the website of the radio, etc.
</p>
<p>
The parameter <code>streams</code> is a list of pairs of strings describing the format of the
stream and the url of the stream. We use a list here because one radio can be
broadcasted under multiple stream formats. The format should always be of the
form <code>codec/bitrate</code> (e.g. <code>mp3/128k</code>) or <code>codec</code> if it is encoded in variable
bitrate.
</p>
<p>
You can register a stream with any <code>user</code> and <code>password</code> parameters. Those
parameters are only useful if you use additional services such as the
command-line client, or if you want to claim that you “own” a registered radio.
All this is relatively informal for now, but may be tightened in future
developments of Flows.
</p>
<h3>Getting information from flows</h3>
<p>
If you develop a website and registered your radio as explained above, flows can
be used as a convenient way to retrieve metadata in javascript, get a list of
friendly radios, etc. The flows service currently consists of a list of radios
broadcasting using Liquidsoap, with their corresponding streams and
metadata.
</p>
<h4>List of radios</h4>
<p>
<b>Note: When the list gets big enough, this API should be changed to return paginated results.</b>
</p>
<p>
A list of radios, encoded in JSON format, can be obtained by querying the
following url:
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radios
</pre>
<p>
Output is a JSON string like this:
</p>
<pre class="syntax javascript">[{ "token" : "a60f5cadf2645321d4d061896318a2d99f2ff6a6",
"name" : "RadioPi - Canal Jazz",
"website" : "http://www.radiopi.org/",
"description" : "Cool vibes from Chatenay!",
"genre" : "jazz",
"longitude" : 2.26670002937317,
"latitude" : 48.7667007446289,
"title" : "Bud Powell - Un Poco Loco",
"artist" : "Va-1939-1999 - 60 Ans De Jazz",
"streams" : [{ "format" : "mp3/128k",
"url" : "http://radiopi.org:8080/jazz" }]}
...
</pre>
<h4>Single radio</h4>
<p>
A single radio, encoded in JSON format, can be obtained by querying the
following url:
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radio?name=foo&website=bar
</pre>
<p>
All argument are optional and should be in UTF8 and properly encoded for a HTTP
GET request.
</p>
<p>
A direct request using a radio's token can also be performed at this URL:
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radio/:token
</pre>
<p>
Output is a JSON string like this:
</p>
<pre class="syntax javascript">{ "token" : "a60f5cadf2645321d4d061896318a2d99f2ff6a6",
"name" : "RadioPi - Canal Jazz",
"website" : "http://www.radiopi.org/",
"description" : "Cool vibes from Chatenay!",
"genre" : "jazz",
"longitude" : 2.26670002937317,
"latitude" : 48.7667007446289,
"title" : "Bud Powell - Un Poco Loco",
"artist" : "Va-1939-1999 - 60 Ans De Jazz",
"streams" : [{ "format" : "mp3/128k",
"url" : "http://radiopi.org:8080/jazz" }]}
</pre>
<h4>Stream redirection</h4>
<p>
Flows can also be used to provide a single url for all your listeners, allowing
you to change the actual listening url of your radio while preserving your
playlists.
</p>
<p>
If you radio's token is <code>:token</code> and has a stream of format <code>:format</code>, then the
following url will redirect any request to your stream's URL.
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radio/:token/:format
</pre>
<h4>Playlist</h4>
<p>
As for streams, if you radio's token is <code>:token</code> then the following link will
return a <a href="http://en.wikipedia.org/wiki/PLS_(file_format" target="_blank">PLS</a>) playlist:
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radio/:token.pls
</pre>
<h4>Real-time notifications</h4>
<p>
It is oftentimes difficult to properly implement a regular update of your
radio's currently playing information on a website or an online player. Using
Flows, you can very easily implement real-time notifications of the song
currently being played by your radio.
</p>
<p>
First, you need to know your radio's token. You can do so by querying a single
radio, as described above, or querying all radios and finding yours in the list.
</p>
<p>
Then, in your webpage's head, you need to add javascript code adapted from this
example:
</p>
<pre class="syntax html"><script src="http://flows.liquidsoap.fm/socket.io/socket.io.js"></script>
<script type="text/javascript">
var socket = io.connect("http://flows.liquidsoap.fm");
socket.emit('join', radio_token);
socket.on('joined', function (radio) {
console.log("Successfully joined " + radio.name + " notification channel. Current title is: " + radio.title + ".");
});
socket.on('error', function (data) {
console.log("Error: " + data + ".");
});
socket.on(radio_token, function (data) {
console.log("Got new notification " + data.cmd + " for radio " + data.radio.name + ": " + JSON.stringify(data));
});
</script>
</pre>
<p>
Received messages are objects of the form:
</p>
<pre class="syntax javascript">{ cmd : "metadata",
radio : { token : "a60f5cadf2645321d4d061896318a2d99f2ff6a6",
name : "RadioPi - Canal Jazz",
website : "http://www.radiopi.org/",
description : "Cool vibes from Chatenay!",
genre : "jazz",
longitude : 2.26670002937317,
latitude : 48.7667007446289,
title : "Bud Powell - Un Poco Loco",
artist : "Va-1939-1999 - 60 Ans De Jazz",
streams : [{ format : "mp3/128k",
url : "http://radiopi.org:8080/jazz" }]}}
</pre>
<p>
Messages with command <code>"metadata"</code> are the one you want to use to update
information displayed about your radio.
</p>
<h4>Twitter notifications</h4>
<p>
<b>Note: The twitter API is deprecated for now.</b>
</p>
<p>
You can register twitter notifications on any twitter account with radio that
you own. The API is designed to allow implementing this feature on your
website. It works as follows:
</p>
<p>
First you issue a <code>HTTP</code> <code>GET</code> request, authenticated with your radio
credentials at this address:
</p>
<pre class="syntax ">http://flows.liquidsoap.fm/radio/:token/twitter/auth?redirect_to=:link
</pre>
<p>
Then you should receive a response of the form:
</p>
<pre class="syntax ">{"url":"https://api.twitter.com/oauth/authenticate?oauth_token=..."}
</pre>
<p>
You should then visit the returned url with a browser or redirect your website
visitor to this address. There, twitter should ask you to authorize the <code>Savonet
Flows</code> application for the twitter user that you or your visitor are using.
</p>
<p>
Once done, you should be automatically redirected to <code>:link</code> where <code>:link</code> is
the parameter passed in the initial <code>HTTP</code> <code>GET</code> request. From this point, all
metadata updates for the that radio should be forwarded to the twitter account
that was just authorized.
</p>
<h4>Command-line client</h4>
<p>
A command-line client is also available. It can be used to:
</p>
<ul>
<li>
Change your radio's name</li>
<li>
Change your radio's location</li>
<li>
Register and unregister twitter notifications</li>
</ul>
<p>
The code is still being developped. It can be accessed at this url:
<a href="https://github.com/savonet/flows-client">https://github.com/savonet/flows-client</a>
</p>
</div></div>
<div>
<div id="footer"> 2003-2013 Savonet team</div>
</div>
</div>
</body></html>
|