From db410bf64e9204692935e5d64048598fcee5dc62 Mon Sep 17 00:00:00 2001 From: Radu Suciu Date: Tue, 8 Sep 2020 14:28:49 -0700 Subject: [PATCH] Update README.md --- README.md | 70 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 9c9da86..1b83aca 100644 --- 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: `

{{artist}} - {{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 + + + + + + + % for track in tracks: +

{{track.get('artist', '')}} - {{track.get('title')}}

+ % end + + +``` + +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`.