release: v0.3.4 (Markdown auto-chapters); docs updated

Author: prateekjain24

docs/RELEASE_NOTES.md

@@ -51,3 +51,8 @@ v0.3.3 (2025-09-08)
 --------------------
 - fix(cache): correct cache directory parsing (`<root>/<video>/<engine>/<model>/<hash>`) when deriving `video_id`, ensuring cache listings and exports find entries.
 - test(cache): add test to validate video_id parsing and cache scanning.
+
+v0.3.4 (2025-09-08)
+--------------------
+- feat(export-md): auto-chapters synthesis when missing (`--md-auto-chapters-min N`), generating a chapter outline at fixed intervals.
+- docs: README updated with auto-chapters option.

docs/release_github_v0.3.2.md

@@ -0,0 +1,12 @@
+# TubeScribe v0.3.2 — Export from Cache Fixes
+
+## Fixes
+- cache: `scan_cache` and artifact checks now accept legacy `<video_id>.json/.srt` alongside canonical `transcript.json/captions.srt`.
+- cli(export): when `transcript.json` is missing, fall back to `<video_id>.json` for cached export.
+
+## Upgrade
+`pipx upgrade tubescribe` or `pip install -U tubescribe`
+
+## Notes
+This unblocks `ytx export --video-id <id> --to md --output-dir ./notes` on older caches.
+

docs/release_github_v0.3.4.md

@@ -0,0 +1,13 @@
+# TubeScribe v0.3.4 — Auto‑Chapters for Markdown
+
+## Feature
+- Markdown export can now synthesize chapters when a video has none.
+  - CLI: `--md-auto-chapters-min N` adds a chapter outline every N minutes.
+  - Works alongside existing features: frontmatter, summary/bullets, transcript.
+
+## Example
+`ytx export --video-id <id> --to md --output-dir ./notes --md-frontmatter --md-auto-chapters-min 5`
+
+## Upgrade
+`pipx upgrade tubescribe` or `pip install -U tubescribe`
+

ytx/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tubescribe"
-version = "0.3.3"
+version = "0.3.4"
 description = "CLI to transcribe YouTube audio via Whisper (local) or Gemini (cloud)"
 readme = "README.md"
 authors = [

ytx/src/ytx/cache.py

@@ -177,7 +177,8 @@ def artifacts_exist(paths: ArtifactPaths) -> bool:
         return True
     # fallback to <video_id>.json/.srt
     try:
-        vid = paths.dir.parents[3].name
+        # <root>/<video_id>/<engine>/<model>/<hash>
+        vid = paths.dir.parents[2].name
     except Exception:
         vid = None
     if vid:
@@ -231,10 +232,14 @@ def read_transcript_doc(paths: ArtifactPaths) -> "TranscriptDoc":
         raw = _read_json_bytes(paths.transcript_json)
     except CacheError:
         # Fallback to <video_id>.json if present
+        vid = None
         try:
-            vid = paths.dir.parents[3].name
+            vid = paths.dir.parents[2].name
+        except Exception:
+            pass
+        if vid:
             raw = _read_json_bytes(paths.dir / f"{vid}.json")
-        except Exception as e:
+        else:
             raise
     try:
         payload = _loads_json(raw)
@@ -418,9 +423,10 @@ def scan_cache(root: Path | None = None) -> list[CacheEntry]:
     entries: list[CacheEntry] = []
     for d in iter_artifact_dirs(root):
         try:
-            video_id = d.parents[3].name
-            engine = d.parents[2].name
-            model = d.parents[1].name
+            # <root>/<video_id>/<engine>/<model>/<hash>
+            video_id = d.parents[2].name
+            engine = d.parents[1].name
+            model = d.parents[0].name
             cfg_hash = d.name
         except Exception:
             continue

ytx/tests/test_cache_scan_videoid.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+from datetime import datetime, timezone
+
+from ytx.cache import scan_cache, build_artifact_paths, write_meta, build_meta_payload
+from ytx.config import AppConfig
+from ytx.models import VideoMetadata
+
+
+def test_scan_cache_reads_correct_video_id(tmp_path: Path):
+    # Arrange: create canonical files under <root>/<vid>/<engine>/<model>/<hash>/
+    vid = "TLSSVT1GI2Y"
+    cfg = AppConfig(engine="whisper", model="small")
+    paths = build_artifact_paths(video_id=vid, engine=cfg.engine, model=cfg.model, config_hash="deadbeef", root=tmp_path, create=True)
+    # Create minimal artifacts
+    (paths.transcript_json).write_text("{}", encoding="utf-8")
+    (paths.captions_srt).write_text("1\n00:00:00,000 --> 00:00:00,500\nHi\n", encoding="utf-8")
+    vm = VideoMetadata(id=vid, title="t", duration=1.0, url=f"https://youtu.be/{vid}")
+    write_meta(paths, build_meta_payload(video_id=vid, config=cfg, source=vm, provider=cfg.engine))
+
+    # Act
+    entries = scan_cache(root=tmp_path)
+
+    # Assert
+    assert any(e.video_id == vid for e in entries)
+