Update README.md

radusuciu · Sep 8, 2020 · db410bf · db410bf
1 parent ddd6b2a
commit db410bf
Showing 1 changed file with 50 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -38,34 +38,35 @@ traktor_nowplaying --port 8000 --outfile='nowplaying.txt' --quiet
 
 The help text:
 ```bash
-$ traktor_nowplaying -h
-usage: traktor_nowplaying [-h] [-p PORT] [-q] [-o OUTFILE] [-a]
-                          [-m MAX_TRACKS] [-i] [-v]
+$ traktor_nowplaying --help
+usage: traktor_nowplaying [-h] [-p PORT] [-q] [-f FORMAT] [-o OUTFILE] [-t TEMPLATE] [-a] [-m MAX_TRACKS] [-i] [-v]
 
-Use Traktor's broadcast functionality to extract metadata about the currently
-playing song
+Use Traktor's broadcast functionality to extract metadata about the currently playing song
 
 optional arguments:
   -h, --help            show this help message and exit
   -p PORT, --port PORT  Port to listen on for broadcasts from Traktor
   -q, --quiet           Suppress console output of currently playing song
+  -f FORMAT, --format FORMAT
+                        Custom format to use when outputting tracks
   -o OUTFILE, --outfile OUTFILE
-                        Provide a file path to which the currently playing
-                        song should be written
-  -a, --append          If writing to file, appends newest track to end of
-                        file instead of overwriting the file
+                        Provide a file path to which the currently playing song should be written
+  -t TEMPLATE, --template TEMPLATE
+                        Template file to use for output. Templating is implemented using Bottle SimpleTemplate
+                        (https://bottlepy.org/docs/0.12/stpl.html). See README for more details on use. Note: the
+                        --format options is ignored when using a custom template file. Take care when using templates
+                        provided by others on the internet as they can contain malicious code.
+  -a, --append          If writing to file, appends newest track to end of file instead of overwriting the file
   -m MAX_TRACKS, --max-tracks MAX_TRACKS
-                        If appending to a file, the maximum number of tracks
-                        to keep in file (by default there is no limit)
-  -i, --interactive     Interactive mode allows for settings to be specified
-                        at runtime. These override command line options.
+                        If appending to a file, the maximum number of tracks to keep in file (by default there is no
+                        limit)
+  -i, --interactive     Interactive mode allows for settings to be specified at runtime. These override command line
+                        options.
   -v, --version         show program's version number and exit
 
-Note that you must configure Traktor to broadcast to localhost and the port
-specified with the -p, or --port option (defaults to 8000). For the format
-setting you can use anything, but I recommend choosing the lowest bitrate for
-the sample rate of your system, so most commonly the best choice is 44100 Hz,
-64 Kbps.
+Note that you must configure Traktor to broadcast to localhost and the port specified with the -p, or --port option
+(defaults to 8000). For the format setting you can use anything, but I recommend choosing the lowest bitrate for the
+sample rate of your system, so most commonly the best choice is 44100 Hz, 64 Kbps.
 ```
 
 To stop the process `Ctrl + C` should suffice.
@@ -87,7 +88,36 @@ listener.start()
 
 For a more elaborate example with a custom callback, see this project: https://github.com/radusuciu/traktor_ice, and [this bit](https://github.com/radusuciu/traktor_ice/blob/b0873cb5e36dbcb87a260900f44a2f1768d5d5c9/traktor_ice/core.py#L60-L74) in particular.
 
+## Customizing output
 
-## Implementation details
+The output of `traktor_nowplaying` can be customized using the `--format` and `--template` options. Both of these functions make use of the [`SimpleTemplate` Engine](https://bottlepy.org/docs/0.12/stpl.html) included with [Bottle 0.12](https://bottlepy.org/docs/0.12/), so anything you can use with Bottle's templates, you can use here.
 
-TODO
+**Note**: Please take care when using format strings or templates provided by others on the internet. These can contain malicious code. I doubt this will be the case since this is such an obscure project and I can't imagine templates being complex enough to hide malware, but you never know.
+
+### `--format`
+
+This option allows for the specification of alternate ways to display tracks. By default, tracks are formatted using a simple template: `{{artist}} - {{title}}`. You can change the order: `{{title}} - {{artist}}`, only display the title `{{title}}`, or sprinkle in some HTML: `<p><strong>{{artist}}</strong> - {{title}}`.
+
+### `--template`
+
+While `--format` allows you to control the display of each individual track, `--template` allows you to specify a template file. This template file will be passed a `tracks` variable that contains a list of tracks to display. Each individual track is a Python `dict` with `artist` and `title` keys. Here's an example:
+
+```html
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8">
+    </head>
+    <body>
+        % for track in tracks:
+        <p><strong>{{track.get('artist', '')}}</strong> - {{track.get('title')}}</p>
+        % end
+    </body>
+</html>
+```
+
+If you save the above as `template.html` you can use it like so: `traktor_nowplaying --template template.html --append`. Note that without setting `--append`, you will only have the latest track being output.
+
+**Note**: Templates don't have to be HTML
+
+**Note**: `--template` overrides `--format`.