tv-recorder 0.1.0__tar.gz

tv_recorder-0.1.0/.codex/skills/tv-recorder-add-channel/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: tv-recorder-add-channel
+description: Add or repair a channel entry in a Python tv-recorder project's defaults.yaml. Use when the user asks to add a public TV/news/live channel, discover or stabilize an HLS m3u8 URL, choose between direct URL/API/browser discovery strategies, configure video/audio selection, or run smoke tests for a tv-recorder channel.
+---
+
+# TV Recorder Add Channel
+
+## Workflow
+
+Use this skill when editing `src/tv_recorder/defaults.yaml` for a `tv-recorder` project.
+
+1. Read `defaults.yaml`, `config.py`, `stream_finder.py`, and `recorder.py` before editing. Preserve the existing schema and local style.
+2. Read the requested channel URL or channel list. If a companion file such as `chaines.md` exists, inspect the relevant lines.
+3. Prefer the least fragile working strategy:
+   - Stable direct HLS URL or public API returning HLS.
+   - Browser discovery with Playwright when the URL is tokenized, embedded, or only emitted after consent/play clicks.
+   - Alternate public HLS only when the official site is geoblocked, stale, DRM-protected, or unusable from the current location.
+4. Validate candidates with a real short ffmpeg capture, not only HTTP status or dry-run. A master manifest can return `200` while every child variant fails.
+5. Patch `defaults.yaml` only after a candidate records successfully.
+6. Run one focused smoke test for the new/changed channel. Use 1 minute unless the user asks otherwise.
+7. Report the source key, strategy used, test result, output path, and any caveat such as geoblocking or third-party alternate feed.
+
+## Discovery
+
+Use these options in order, stopping once one gives a reliable recording:
+
+- **Direct manifest/API**: Check the live page source, network calls, JSON APIs, and public stream indexes for `.m3u8`. Configure `stream_request_urls` and `steps: []`.
+- **Browser discovery**: Configure `start_url`, `stream_url_pattern`, `steps: [{action: wait_for_stream}]`, and add reject patterns for ads, analytics, VOD, or redirector manifests.
+- **JSON response extraction**: Configure `stream_response_url_patterns` and `stream_response_json_keys` when a validation/API endpoint returns the stream URL.
+- **Separate audio HLS**: If the master manifest uses `#EXT-X-MEDIA` audio groups, set `recording.hls.separate_audio: true`, `video.direct_variant: false`, and configure `audio.language`.
+
+Read `references/channel-recipes.md` for concrete recipes and failure patterns before repairing a difficult channel.
+
+## Validation
+
+For each new or repaired channel:
+
+```powershell
+.\.venv\Scripts\tv-recorder.exe <source-key> now 1m --output-dir recordings\smoke-<stamp> --timeout-ms 60000
+```
+
+If validating several channels, cap parallelism. Previous project smoke tests used 3 or 5 concurrent recordings.
+
+After recording, inspect the file with the bundled ffmpeg:
+
+```powershell
+@'
+import subprocess, imageio_ffmpeg
+from pathlib import Path
+ffmpeg = imageio_ffmpeg.get_ffmpeg_exe()
+path = Path(r"<recorded-file.mp4>")
+subprocess.run([ffmpeg, "-hide_banner", "-i", str(path)])
+'@ | .\.venv\Scripts\python.exe -
+```
+
+A successful entry should produce a playable MP4 with nonzero size, about the requested duration, and expected video/audio streams.
+
+## Defaults YAML Pattern
+
+Use stable, lowercase source keys. Keep display names human-readable.
+
+```yaml
+  source-key:
+    display_name: Channel Name
+    start_url: "https://example.com/live"
+    stream_url_pattern: "\\.m3u8(\\?|$)"
+    stream_request_urls:
+      - "https://example.com/live/master.m3u8"
+    stream_url_reject_patterns:
+      - "dai\\.google\\.com"
+    output_extension: "mp4"
+    recording:
+      video:
+        height: 720
+      audio:
+        language: "eng"
+    steps: []
+    user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125 Safari/537.36"
+```
+
+For browser discovery, omit `stream_request_urls` and use:
+
+```yaml
+    steps:
+      - action: wait_for_stream
+```
+
+## Guardrails
+
+- Do not trust a candidate because `Invoke-WebRequest` or `context.request.get()` returns `200`; run ffmpeg for a few seconds.
+- Reject ad manifests such as `dai.google.com` and Dailymotion redirectors when they do not record.
+- Prefer official sources, but accept that a stable direct alternate can be as reasonable as browsing a fragile page.
+- If DRM or HLS SAMPLE-AES appears, do not try to bypass protection. Mark it as unsupported.
+- Keep changes scoped to channel config unless the project lacks a capability needed by multiple channels.

tv_recorder-0.1.0/.codex/skills/tv-recorder-add-channel/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TV Recorder Add Channel"
+  short_description: "Add and validate channels in tv-recorder defaults.yaml."
+  default_prompt: "Add a new tv-recorder channel entry to defaults.yaml and validate it with a short recording smoke test."

tv_recorder-0.1.0/.codex/skills/tv-recorder-add-channel/references/channel-recipes.md

@@ -0,0 +1,105 @@
+# Channel Recipes
+
+Use this reference when a channel is not obvious from `defaults.yaml`.
+
+## Direct HLS
+
+Use `stream_request_urls` with `steps: []` when a manifest records directly. This is fastest and most stable when the URL is not tokenized per session.
+
+Validate with ffmpeg, because a master manifest can be alive while its variants return `400`, `403`, or `404`.
+
+Examples observed in this project:
+- Global News regional feeds: direct Corus `.isml/.m3u8` manifests.
+- CPAC: direct master with separate audio tracks.
+- NHK: old master returned `200` but children failed; `https://masterpl.hls.nhkworld.jp/hls/w/live/smarttv.m3u8` recorded successfully.
+
+## API-Returned Stream
+
+Use `stream_response_url_patterns` and `stream_response_json_keys` when a public endpoint returns a stream URL. Keep browser steps empty if the API is enough.
+
+Example pattern:
+
+```yaml
+stream_request_urls:
+  - "https://service.example/api/live?output=json"
+stream_response_url_patterns:
+  - "service\\.example/api/live"
+stream_response_json_keys:
+  - "url"
+steps: []
+```
+
+## Browser Discovery
+
+Use browser discovery when:
+- the manifest is tokenized per session,
+- a consent or play action is required,
+- the source is embedded in an iframe/player,
+- the direct URL expires quickly.
+
+Start with:
+
+```yaml
+steps:
+  - action: wait_for_stream
+```
+
+The project's auto-start logic tries common consent and play controls. Add explicit steps only when required.
+
+## Reject Patterns
+
+Add `stream_url_reject_patterns` for candidates that are detected but not recordable or not the desired program:
+
+- `dai\\.google\\.com` for ad-insertion manifests.
+- `originpath=/linear/hls` when a provider exposes an ad/linear wrapper instead of the clean live stream.
+- `dmxleo\\.dailymotion\\.com` for Dailymotion manifest wrappers that are not final media.
+- `cdndirector\\.dailymotion\\.com` when ffmpeg receives `403`; prefer the final `live.*.dmcdn.net/...m3u8` variant if discovered.
+
+## Video and Audio Selection
+
+Set `recording.video.height` when the stream has multiple variants. Use `direct_variant: false` when ffmpeg should receive the master manifest, especially when separate audio groups are involved.
+
+For master manifests with separate audio:
+
+```yaml
+recording:
+  hls:
+    separate_audio: true
+  video:
+    height: 720
+    direct_variant: false
+  audio:
+    language: "en"
+```
+
+For French audio, observed language codes may be `fre`, `fra`, or `fr`; use what ffmpeg or the HLS manifest reports.
+
+When audio-description tracks exist, use `reject_comments` if ffmpeg metadata exposes the descriptive track:
+
+```yaml
+audio:
+  language: "fre"
+  comment: "Français"
+  reject_comments:
+    - "audio_dv"
+```
+
+## Failure Meanings
+
+- `403 Forbidden` on the manifest or variants: likely geoblocking, missing headers, expired token, or a redirector that should be rejected.
+- `Output file does not contain any stream`: master was reachable but variants failed or were empty.
+- `SAMPLE-AES` or `KEYFORMAT`: protected HLS; do not attempt to bypass.
+- A small partial file with nonzero size and rc=1: often a late stream interruption, timestamp issue, or too-short capture; retest before changing config.
+- A live endpoint returning `false`, `is_on_air: false`, or no player data can mean the channel is event-based rather than broken.
+- YouTube embeds can expose no HLS and return `EMBEDDER_IDENTITY_DENIED`; do not treat that as a normal HLS channel unless the project intentionally adds a YouTube resolver.
+- Do not replace a channel with a different but similarly named feed just to make a smoke test pass. Keep `TV5MONDE Europe` as Europe, `UK Parliament` as UK Parliament, etc., unless the user explicitly accepts a substitute.
+
+## Smoke Testing
+
+Use 1-minute tests for confidence:
+
+```powershell
+.\.venv\Scripts\tv-recorder.exe <source-key> now 1m --output-dir recordings\channel-smoke --timeout-ms 60000
+```
+
+For many channels, use a small worker pool. This project previously used 3 or 5 simultaneous recordings. Treat repeated failures across 3 attempts as real configuration problems; treat one failure followed by successes as a possible transient.

tv_recorder-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

tv_recorder-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+recordings/
+dist/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/

tv_recorder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tv-recorder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tv_recorder-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: tv-recorder
+Version: 0.1.0
+Summary: Command-line recorder for public live TV streams.
+Project-URL: Homepage, https://github.com/onclefranck/tv-recorder
+Project-URL: Repository, https://github.com/onclefranck/tv-recorder
+Project-URL: Issues, https://github.com/onclefranck/tv-recorder/issues
+Author: tv-recorder contributors
+License: MIT License
+        
+        Copyright (c) 2026 tv-recorder contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,ffmpeg,hls,playwright,recorder,tv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: imageio-ffmpeg>=0.6.0
+Requires-Dist: playwright>=1.44
+Requires-Dist: pytimeparse2>=1.7.1
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tv-recorder
+
+Command-line recorder for public live TV streams.
+
+## Local Installation
+
+```powershell
+python -m pip install -e .
+```
+
+Chromium is installed automatically on first use if Playwright does not already have it.
+
+The recorder uses the `ffmpeg` binary provided by `imageio-ffmpeg`.
+
+## Usage
+
+```powershell
+tv-recorder radio-canada.ca now 2h
+```
+
+The general form is:
+
+```text
+tv-recorder SOURCE START DURATION
+```
+
+Examples:
+
+```powershell
+tv-recorder radio-canada.ca now 30m
+tv-recorder radio-canada.ca 2026-05-24T20:00:00 2h --output-dir recordings
+tv-recorder tvaplus.ca now 30m
+tv-recorder telequebec.tv now 30m
+tv-recorder cpac-english now 30m
+tv-recorder cpac-francais now 30m
+tv-recorder canal-assemblee-nationale now 30m
+tv-recorder globalnews-national now 30m
+tv-recorder globalnews-montreal now 30m
+tv-recorder radio-canada.ca now 10m --headful
+tv-recorder radio-canada.ca now 10m --dry-run
+```
+
+`START` accepts `now` or a local ISO date. `DURATION` accepts values such as `90s`, `30m`, `2h`, or `01:30:00`.
+
+## Configuration YAML
+
+The package includes a default configuration. To replace it, provide your own YAML file:
+
+```powershell
+tv-recorder radio-canada.ca now 2h --config my-file.yaml
+```
+
+Each source can define:
+
+- `start_url`: page to open with Playwright.
+- `stream_url_pattern`: regular expression used to identify stream URLs.
+- `stream_request_urls`: optional JSON endpoints to call before browser steps.
+- `stream_response_url_patterns`: response URL patterns whose JSON can contain stream URLs.
+- `stream_response_json_keys`: JSON keys whose values should be treated as stream URLs.
+- `stream_url_reject_patterns`: stream URL patterns to ignore.
+- `recording`: video/audio track selection.
+- `steps`: browser interaction recipe before stream detection.
+- `output_extension`: output file extension.
+- `user_agent`: optional user-agent for browser and recorder requests.
+
+Track selection:
+
+```yaml
+recording:
+  video:
+    height: 720
+  audio:
+    language: "fre"
+    reject_comments:
+      - "audio_dv"
+```
+
+If no video track matches the requested height, the highest available resolution is used. For audio, rejected comments are filtered first, then language and comment preferences are used to choose the main track.
+
+Supported steps:
+
+```yaml
+steps:
+  - action: wait_for_stream
+  - action: wait_for_selector
+    selector: "button.vjs-big-play-button"
+  - action: click_by_text
+    text: "EN DIRECT"
+  - action: click_by_selector
+    selector: "button:has-text('Play')"
+    fallback:
+      action: click_by_text
+      text: "Play"
+    required: true
+    timeout_ms: 30000
+```
+
+## Notes
+
+The recorder uses browser automation to discover streams when a channel does not expose a stable feed URL, then records the selected audio/video tracks without re-encoding. This version starts the recording at the requested time in the current process. A real system scheduler can be layered on top of the same command later.
+
+## Publishing
+
+Install packaging tools:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Build and check the package:
+
+```powershell
+python -m build
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first:
+
+```powershell
+python -m twine upload --repository testpypi dist/*
+```
+
+Publish to PyPI:
+
+```powershell
+python -m twine upload dist/*
+```
+
+Before publishing, update `version` in `pyproject.toml` and `__version__` in `src/tv_recorder/__init__.py`, then rebuild from a clean `dist` directory.

tv_recorder-0.1.0/README.md

@@ -0,0 +1,129 @@
+# tv-recorder
+
+Command-line recorder for public live TV streams.
+
+## Local Installation
+
+```powershell
+python -m pip install -e .
+```
+
+Chromium is installed automatically on first use if Playwright does not already have it.
+
+The recorder uses the `ffmpeg` binary provided by `imageio-ffmpeg`.
+
+## Usage
+
+```powershell
+tv-recorder radio-canada.ca now 2h
+```
+
+The general form is:
+
+```text
+tv-recorder SOURCE START DURATION
+```
+
+Examples:
+
+```powershell
+tv-recorder radio-canada.ca now 30m
+tv-recorder radio-canada.ca 2026-05-24T20:00:00 2h --output-dir recordings
+tv-recorder tvaplus.ca now 30m
+tv-recorder telequebec.tv now 30m
+tv-recorder cpac-english now 30m
+tv-recorder cpac-francais now 30m
+tv-recorder canal-assemblee-nationale now 30m
+tv-recorder globalnews-national now 30m
+tv-recorder globalnews-montreal now 30m
+tv-recorder radio-canada.ca now 10m --headful
+tv-recorder radio-canada.ca now 10m --dry-run
+```
+
+`START` accepts `now` or a local ISO date. `DURATION` accepts values such as `90s`, `30m`, `2h`, or `01:30:00`.
+
+## Configuration YAML
+
+The package includes a default configuration. To replace it, provide your own YAML file:
+
+```powershell
+tv-recorder radio-canada.ca now 2h --config my-file.yaml
+```
+
+Each source can define:
+
+- `start_url`: page to open with Playwright.
+- `stream_url_pattern`: regular expression used to identify stream URLs.
+- `stream_request_urls`: optional JSON endpoints to call before browser steps.
+- `stream_response_url_patterns`: response URL patterns whose JSON can contain stream URLs.
+- `stream_response_json_keys`: JSON keys whose values should be treated as stream URLs.
+- `stream_url_reject_patterns`: stream URL patterns to ignore.
+- `recording`: video/audio track selection.
+- `steps`: browser interaction recipe before stream detection.
+- `output_extension`: output file extension.
+- `user_agent`: optional user-agent for browser and recorder requests.
+
+Track selection:
+
+```yaml
+recording:
+  video:
+    height: 720
+  audio:
+    language: "fre"
+    reject_comments:
+      - "audio_dv"
+```
+
+If no video track matches the requested height, the highest available resolution is used. For audio, rejected comments are filtered first, then language and comment preferences are used to choose the main track.
+
+Supported steps:
+
+```yaml
+steps:
+  - action: wait_for_stream
+  - action: wait_for_selector
+    selector: "button.vjs-big-play-button"
+  - action: click_by_text
+    text: "EN DIRECT"
+  - action: click_by_selector
+    selector: "button:has-text('Play')"
+    fallback:
+      action: click_by_text
+      text: "Play"
+    required: true
+    timeout_ms: 30000
+```
+
+## Notes
+
+The recorder uses browser automation to discover streams when a channel does not expose a stable feed URL, then records the selected audio/video tracks without re-encoding. This version starts the recording at the requested time in the current process. A real system scheduler can be layered on top of the same command later.
+
+## Publishing
+
+Install packaging tools:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Build and check the package:
+
+```powershell
+python -m build
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first:
+
+```powershell
+python -m twine upload --repository testpypi dist/*
+```
+
+Publish to PyPI:
+
+```powershell
+python -m twine upload dist/*
+```
+
+Before publishing, update `version` in `pyproject.toml` and `__version__` in `src/tv_recorder/__init__.py`, then rebuild from a clean `dist` directory.

tv_recorder-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tv-recorder"
+version = "0.1.0"
+description = "Command-line recorder for public live TV streams."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "tv-recorder contributors" },
+]
+keywords = ["cli", "ffmpeg", "hls", "playwright", "recorder", "tv"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "imageio-ffmpeg>=0.6.0",
+  "playwright>=1.44",
+  "pytimeparse2>=1.7.1",
+  "PyYAML>=6.0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "twine>=5.0",
+]
+
+[project.scripts]
+tv-recorder = "tv_recorder.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/onclefranck/tv-recorder"
+Repository = "https://github.com/onclefranck/tv-recorder"
+Issues = "https://github.com/onclefranck/tv-recorder/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tv_recorder"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/tv_recorder/defaults.yaml" = "tv_recorder/defaults.yaml"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tv_recorder-0.1.0/src/tv_recorder/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"