README.rst

   1 ********************
   2 Noxon iRadio gateway
   3 ********************
   4 Push your own content onto `Noxon iRadio`__ devices:
   5 RSS feeds, text files and MediaTomb server structures.
   6
   7 This tool makes it possible to push own data into the menu
   8 entries "Internet Radio", "Podcasts" and "My Noxon" without relying
   9 on the official Terratec servers.
  10
  11 __ http://www.noxonradio.de/
  12
  13
  14 .. contents::
  15
  16
  17 ========
  18 Features
  19 ========
  20 - Customize the Noxon iRadio menus "Internet Radio", "Podcasts" and "My Noxon"
  21 - Show Mediatomb UPnP server content in "Internet Radio", so that you
  22   don't have to restart your iRadio because it does not find the UPnP server
  23   after a day of standby
  24 - Display text files and run shell scripts from the menu (home automation)
  25 - Podcast RSS feed support
  26 - Discoverable with your web browser
  27 - Transcoding of non-mp3 file types to ``.mp3`` that iRadios can play
  28 - Single file mode for children that want to listen to a single story
  29   before sleeping
  30
  31
  32 RSS feed support
  33 ================
  34 Simpy write a podcast's mp3 RSS feed URL into a  ``.url`` file in
  35 the ``var/`` directory structure, and your radio will show you a
  36 folder with all episodes.
  37 Enter an episode to play it.
  38
  39 The Noxon iRadios do only allow a single HTTP redirect when they access a URL
  40 to play, but many podcast feeds send you for tracking purposes through 3 or
  41 more redirects until you reach the final mp3 URL.
  42
  43 noxon-gateway resolves the redirections for the iRadio, so that this will
  44 not be a problem.
  45
  46
  47 Creating an RSS feed
  48 --------------------
  49 You have to know the URL to the podcast's mp3 RSS feed, e.g.
  50 ``http://cast.example.org/news.rss``.
  51
  52 Create a file ``Cast News.url`` in ``var/podcasts/`` and write the RSS URL
  53 into it.
  54 That's all.
  55
  56 When accessing the "Podcasts" menu from your noxon iRadio, you'll see a
  57 directory ``Cast News`` that contains all podcast episodes.
  58
  59
  60 Single file mode
  61 ================
  62 Your kid only wants to listen to this one single story before sleeping.
  63 You start it, set the 15 minute sleep timer and leave the room.
  64
  65 After 15 minutes the child comes out and complains that the radio switched
  66 off within the second story and it wants to hear it to the end.
  67
  68 To get around such issues, you can enable "single file directories"
  69 for certain folders.
  70
  71 Each folder with audio files within this configured paths have a special
  72 directory "Einzeln" (single), which have separate folders for each audio
  73 file. Each of this separate folders only have the single audio file in them.
  74
  75 When playing this file, the iRadio will stop playing after the one file
  76 is over.
  77
  78
  79 Supported radios
  80 ================
  81 This is the list of iRadios known to work with ``noxon-gateway``:
  82
  83 - `Noxon iRadio`__ (original white version)
  84 - `Noxon iRadio cube`__
  85
  86 Others should work.
  87 If you know of unlisted radios that do work with this tool, please tell me.
  88
  89 __ http://ftp.noxonradio.de/index.php?dir=NOXON%2FNOXON_iRadio%2F
  90 __ http://ftp.noxonradio.de/index.php?dir=NOXON%2FNOXON_iRadio_Cube%2F
  91
  92
  93 Web browser support
  94 ===================
  95 You can discover the noxon-gateway contents with your web browser.
  96 Point your browser to the gateway's domain and start browsing:
  97
  98 .. image:: docs/screenshots/browsing.png
  99
 100 This works because the XML files delivered by noxon-gateway contain the
 101 link to an XSLT__ file that converts the XML structure to HTML that
 102 browsers understand.
 103
 104 Works at least with Firefox 42 and Chromium 45.
 105
 106 __ http://www.w3.org/TR/xslt
 107
 108
 109 ===================================
 110 Customizing the directory structure
 111 ===================================
 112 The ``var/`` directory contains three directories you can fill with
 113 your own content.
 114
 115 ================ ==================
 116 Menu item        ``var/`` Directory
 117 ================ ==================
 118 Internet Radio   ``internetradio``
 119 Podcasts         ``podcasts``
 120 My Noxon         ``mynoxon``
 121 ================ ==================
 122
 123 You can put folders and files into this directories.
 124
 125 The ``internetradio`` directory is hard-coded to display the contents
 126 of a MediaTomb UPnP server.
 127 You can remove the check in ``index.php#handleRequest()`` if you do not
 128 want this.
 129
 130
 131 File types
 132 ==========
 133 Directory
 134   A directory is browsable by your Noxon radio
 135 ``.txt`` file
 136   Text files are rendered as un-actionable lists, one list item per line.
 137
 138   Empty lines get removed, consecutive spaces get collapsed.
 139 ``.url`` file
 140   Podcast feed URL file.
 141
 142   Simply contains the URL to the podcast's MP3 RSS feed.
 143 executable file
 144   Script is shown as directory and gets executed when navigating
 145   into it.
 146   Output is shown as it is for ``.txt`` files.
 147
 148   I use it to control my house's heating system from the radio.
 149 ``*.auto*`` (executable)
 150   Script gets executed when browsing the folder.
 151   The output is integrated into the directory listing with the same
 152   rules as for ``.txt`` files.
 153
 154   You can use this to show the current time within the directory listing.
 155
 156 File extensions get removed for display purposes.
 157
 158
 159 Sorting
 160 =======
 161 Files and directory are sorted alphabetically and get listed
 162 in this order.
 163
 164 You can prefix your files and directories with ``[0-9]+_``,
 165 which lets you influence sorting and gets removed in the
 166 listings.
 167
 168 Consider the following files::
 169
 170     01_temp.auto.sh
 171     02_warmer.sh
 172     03_colder.sh
 173
 174 Would render as::
 175
 176     Temperature: 23°C
 177     warmer
 178     colder
 179
 180 (given that ``01_temp.auto.sh`` outputs the temperature string)
 181
 182
 183 =====
 184 Setup
 185 =====
 186
 187 Hosts
 188 =====
 189 The following hosts must point to your server and be handled
 190 by this tool::
 191
 192     radio567.vtuner.com
 193     radio5672.vtuner.com
 194     gatekeeper.my-noxon.net
 195
 196
 197 Configure this in your router or the DNS server your iRadio devices use.
 198
 199
 200 MediaTomb
 201 =========
 202 To be able to browse a MediaTomb server, copy ``data/config.php.dist`` to
 203 ``data/config.php`` and fill it with mediatomb web interface credentials.
 204
 205 You also have to install the `Services_Mediatomb`__ library via `PEAR`__::
 206
 207     $ pear channel-discover zustellzentrum.cweiske.de
 208     $ pear install zz/services_mediatomb-alpha
 209
 210 __ http://zustellzentrum.cweiske.de/index.php?package=Services_MediaTomb
 211 __ http://pear.php.net/
 212
 213
 214 Transcoding
 215 ===========
 216 If you have non-mp3 files in your audio collection, install `ffmpeg`__
 217 on the noxon-gateway server.
 218 Transcoding will start automatically when the player accesses a file
 219 that is not in ``audio/mpeg`` format.
 220
 221 __ http://ffmpeg.org/
 222
 223
 224 ===================
 225 About noxon-gateway
 226 ===================
 227
 228 Homepage
 229 ========
 230 The source code is available at http://git.cweiske.de/noxon-gateway.git/
 231 and mirrored at https://github.com/cweiske/noxon-gateway.
 232
 233
 234 License
 235 =======
 236 This application is available under the `AGPL v3`__ or later.
 237
 238 __ http://www.gnu.org/licenses/agpl.html
 239
 240
 241 Author
 242 ======
 243 Written by `Christian Weiske`__, cweiske@cweiske.de
 244
 245 __ http://cweiske.de/