From 017f08b92c5c9637307271d9a56cd9fb49a8edec Mon Sep 17 00:00:00 2001 From: Josh Jacobs Date: Sat, 4 Jul 2026 07:07:02 +0100 Subject: [PATCH] docs: fill README gaps for post_script, notices, and config example Document hook timeout/executable requirements, tick notice output, fix the example config path, and add post_script to config.yml.example. Co-authored-by: Cursor --- README.md | 28 ++++++++++++++++++++++++---- config/config.yml.example | 1 + 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ecc8c290..9b61e4ec 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ uv run python streamdl.py -config ./config/config.yml -time 300 ## Config File -Basic YAML format. See `config/config.yaml.example` for a couple of test sites. +Basic YAML format. See `config/config.yml.example` for a couple of test sites. ```yaml - site: twitch.tv @@ -152,7 +152,7 @@ volumes: ## Post-Download Script Hook -You can configure a script to run automatically after each successful download. The script is set per-site using the `post_script` field: +You can configure a script to run automatically after each successful download — for both live streams and VODs. The script is set per-site using the `post_script` field: ```yaml - site: twitch.tv @@ -162,7 +162,7 @@ You can configure a script to run automatically after each successful download. quality: best ``` -The script receives the file path as its first argument, and additional context via environment variables: +The script must exist and be executable (`chmod +x /scripts/transcode.sh`). It receives the file path as its first argument, and additional context via environment variables: | Variable | Description | Example | |---|---|---| @@ -171,7 +171,26 @@ The script receives the file path as its first argument, and additional context | `STREAMDL_SITE` | Site domain | `twitch.tv` | | `STREAMDL_TYPE` | Download type | `live` or `vod` | -The script runs asynchronously and will not block other downloads. If the script fails, an error is logged but StreamDL continues operating normally. +The script runs asynchronously and will not block other downloads. If the script fails or exceeds the timeout, an error is logged but StreamDL continues operating normally. Use `STREAMDL_POST_SCRIPT_TIMEOUT` (seconds, default `1800`) to cap how long a hook may run. + +**Docker:** Mount your script directory into the container and point `post_script` at the in-container path: + +```yaml +volumes: + - ./scripts:/scripts:ro +``` + +## Tick Notices + +At the end of each check cycle, StreamDL logs a wait line followed by any actionable notices collected during that tick: + +``` +Waiting 60s until next check... +--- notices --- +[day9tv] Requested format '1080p60' unavailable; using default selection +``` + +Notices cover things like quality fallbacks, rate-limit skips, and download failures. Each notice is shown at most once per channel until the channel goes offline (live) or the condition clears, so repeated warnings within a tick are deduplicated. ## Environment Variables @@ -188,6 +207,7 @@ Some of these are also available as flags to the `streamdl` command, this is a # | `UMASK` | File permission mask in octal format (e.g. "022"). Controls default permissions for created files and directories | `022` | | `PUID` | User ID that will own the files/directories created by the container (Docker only) | `1000` | | `PGID` | Group ID that will own the files/directories created by the container (Docker only) | `1000` | +| `STREAMDL_POST_SCRIPT_TIMEOUT` | Maximum seconds a post-download hook may run before being killed | `1800` | ### User ID and Group ID Configuration diff --git a/config/config.yml.example b/config/config.yml.example index 3ba4eeb3..41ee01d2 100644 --- a/config/config.yml.example +++ b/config/config.yml.example @@ -1,4 +1,5 @@ - site: twitch.tv + # post_script: /scripts/transcode.sh # Optional: run after each live/VOD download channels: - name: kaypealol quality: best