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