Add README

1 files changed, 79 insertions, 0 deletions

@@ -0,0 +1,79 @@
+# RADISH
+## radio player in sh
+
+I just want a simple script to play radio sometimes, or shuffle music on my
+computer, or play noise.  I don't need tagging, playlist building, blah blah
+blah.  So, I wrote RADISH.
+
+## Usage
+
+Copied from `radish -h`:
+
+```
+RADISH: radio, music, static
+USAGE:  radish [-h|-k|-r|-s|-S]
+  radish -l [NAME]
+  radish [STATION]
+
+FLAGS:
+ -h    Show this help and exit.
+ -s    Show radish's status and exit.
+ -S    Show radish's status indefinitely.
+ -k    Kill the currently-playing radish invocation.
+ -r    Replay most recently-played station.
+
+OPTIONS:
+ -l [NAME]  List available stations.
+    If NAME is given, narrow the list to those matching it.
+
+PARAMETERS:
+ STATION  Which configured station to play.
+          Stations are defined in the $RADISH_STATION_FILE
+          (default: /home/case/etc/radish/stations).
+          If STATION is not present, or if it matches
+          more than one station, radish will present a menu.
+```
+
+## Configuration
+
+A default `radish.stations` is provided in this repo; save it to
+`$XDG_CONFIG_HOME/radish/stations` and edit as you see fit.
+
+Radish's `station` file is a tab-separated file with the following schema:
+
+```
+URL     DESCRIPTION     TAGS
+```
+
+Lines starting with `#` are ignored as comments.
+
+A `URL` can be the URL of an internet radio or other stream, or one of
+`file://<FOLDER>`, `shuf://<FOLDER>`, or `noise://<NOISE-SPEC>`.  The `file:`
+protocol simply finds all music files underneath `FOLDER` and plays them in
+order.  `shuf:` does the same, but shuffles the files.  `noise:` uses SoX's
+`play` binary to generate noise.
+
+**NOTE**: Currently the `noise:` URL parsing doesn't work.  Patches welcome!
+
+**NOTE**: I'm looking at using a previously-existing playlist format, like `pls`
+or `m3u`, instead of this ad-hoc tab-separated deal.  Expect change in this area.
+
+## Installation
+
+```
+# make install
+```
+
+## Uninstallation
+
+```
+# make uninstall
+```
+
+## Contributing
+
+Patches, comments, complaints are welcome.  You can email me at the address
+listed on the bottom of this page.
+
+RADISH and its associated files are licensed under the Fair License.  See
+COPYING for more details.