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