From 410e624d69d2c72aa584b3c5bb934f8509e4ec3f Mon Sep 17 00:00:00 2001 From: Jordan Date: Fri, 9 Sep 2022 12:36:50 -0700 Subject: docs: readme housekeeping, clarification --- README.md | 59 ++++++++++++++++++++++++----------------------------------- 1 file changed, 24 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 93455fe..97973bd 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,28 @@ # Roka -Stream directory of audiobooks to podcasting apps via RSS. - -A screenshot of the web interface is [available here](screenshots/web.png). +Stream a directory of audiobooks to podcast apps over an RSS XML feed uniquely +generated for each audiobook. A screenshot of the web interface is +[available here](screenshots/web.png). ## Installation -1. Copy and populate app.cfg and uwsgi.ini from examples +1. Copy and populate `app.cfg` and `uwsgi.ini` from examples, or pass + configuration key/values as a JSON string with the `--config` parameter. -2. Install python dependencies flask and uwsgi +2. Install Python dependencies flask and uwsgi. ```bash pip install --user flask uwsgi ``` -3. Run roka.py with --scan to populate audiobook JSON cache (can be re-run to - update cache upon download of new books) +3. Populate audiobook JSON cache; can be re-run to update cache upon download of + new books. ```bash ./roka.py --scan ``` -4. Execute uwsgi.sh to start the server +4. Run uwsgi.sh to start the server. ```bash ./uwsgi.sh @@ -33,10 +34,10 @@ In addition to running as a server, Roka can also generate a static index and set of RSS feeds that can be deployed to static hosting. This mode does not support a username and password. -1. Set `BASE_URL` in app.cfg to the base url where the static site will be - uploaded. +1. Populate `BASE_URL` in `app.cfg` to the base url where the static site will + be uploaded. -2. Run roka.py with the `--generate ` parameter, where +2. Run `roka.py` with the `--generate ` parameter, where `` is an output directory to place the generated site. All audiobook files will be copied to this location. @@ -49,30 +50,18 @@ support a username and password. ## Design decisions -1. Directories contained within config:ROOT_PATH are marked as audiobooks if and - only if they contain at least one MP3 file - -2. Audiobooks are uniquely identifiable by the collective hash of each MP3 file - contained in the audiobook directory - - * Pro: If the directory structure is changed or files are moved, RSS/download - link integrity is maintained, preserving app-side listening progress and - history - - * Con: Each MP3 file is hashed, which can be slow on spinning rust w/ large - collections - -3. XML pubDate and list order is derived from MP3 track attributes; if not - present or duplicates exist, tracks are sorted alphanumerically +1. Directories contained within `ROOT_PATH` are marked as audiobooks if and only + if they contain at least one MP3 file. - if a book's track numbers are unique but incorrect, a preference for filename - sort can be established by creating an 'ignore_tracknum' file in the - audiobook's path +2. Audiobooks are uniquely identified in the web interface by the collective + hash of each MP3 file contained in the audiobook directory. If the directory + structure is changed or files are moved, RSS/download link integrity is + maintained, preserving app-side listening progress and history. -4. No rebuild endpoint exists; cache-affecting routines are run externally by - calling roka.py directly +3. XML `pubDate` and list order is derived from MP3 track attributes; if not + present or duplicates exist, tracks are sorted alphanumerically. If a book's + track numbers are unique but incorrect, a preference for filename sort can be + established by creating an 'ignore_tracknum' file in the audiobook's path. -5. Configuration can either be placed in a file named `app.cfg`, or it can be - overridden on the terminal by passing a JSON string as the `--config` - parameter. I.E. `./roka.py --generate ./static --config '{"ROOT_PATH": - "/path/to/audiobooks", "BASE_URL": "https://example.com/"}'` +4. No rebuild endpoint exists; cache-affecting routines are executed by calling + `roka.py` directly. -- cgit v1.2.3-54-g00ecf