v1.6.3

v1.6.3

Patch release focused on fail-fast guardrails for mixed-host and stale-spec edge cases.

Added

• scripts/host_env.py for setup/process host fingerprint state
• scripts/run_guarded_pipeline.py guarded orchestrator
• scripts/lint_spec_quality.py pre-build quality linter
• New tests for host guards, spec linting, and timeout planning

Changed

• setup.py now records setup host state and exposes it in --json
• process.py now enforces setup/process host consistency by default
• process.py now supports timeout-planning fail-fast checks
• SKILL.md now gates builds on path validation + quality linting
• CI constrained integration updated for host setup-state seeding

Full Changelog: v1.6.2...v1.6.3

v1.6.2

1.6.2

Patch release focused on workflow hardening for mixed-host execution and safer docx spec builds.

Added

• Pre-build spec path validator (scripts/validate_spec_paths.py) to verify referenced frame/contact-sheet/transcript paths before build-docx.js.
• Test coverage for spec path validation (tests/test_validate_spec_paths.py).

Changed

• SKILL workflow now defines a strict host/sandbox execution contract and requires host-side preflight when execution context changes.
• Added long-run guidance for timeout-constrained shells.
• Added strict gate requiring current-session select_frames.py output and mandatory spec path validation before doc build.
• Expanded failure-mode guidance for PATH drift and stale prior-session frame paths.

Full Changelog: v1.6.1...v1.6.2

v1.6.1

Full Changelog: v1.6.0...v1.6.1

v1.6.0

Reliability fixes driven by a real-world YouTube run inside a Linux sandbox: bot detection on cloud IPs, the 256 KB manifest Read limit, and transcript gaps on locally-downloaded files.

Added

• Android-first YouTube downloads. For public YouTube URLs, download.py now leads with the android player client, which bypasses YouTube's n-challenge without a JavaScript runtime and avoids the 403s the default web client hits from server/cloud IPs. If it can't produce a usable video, it retries once with the web client. When cookies are supplied, the authenticated web session is honored instead (the android client ignores cookies).
• --captions-only retrofit mode. process.py --captions-only --source <url> --out-dir <dir> fetches auto-subtitles and writes transcript.txt without re-downloading or re-extracting the video, then patches any existing manifest(_lite).json transcript fields (including per-chunk slices). This recovers a transcript for an output directory whose video was processed from a separately downloaded local file.

Changed

• Slimmer manifest_lite.json. The lite manifest no longer carries per-frame arrays. On long videos those could push it past the 256 KB Read-tool limit. select_frames.py now transparently loads the full manifest.json to read frame paths, so the existing invocation keeps working.
• Download cache lease is always released. The pipeline runs cache cleanup in a finally, so a failed download can't leave an .in_use lease protecting a cache entry until its TTL.
• Auth-aware cache reuse. A cached anonymous download is no longer served to a later cookie-authenticated request for the same URL.

Docs

SKILL.md and the README document the android-first fallback, the --cookies-from-browser same-OS caveat (run yt-dlp host-side in a sandbox), the preference for pip/pipx yt-dlp over a frozen binary, the --captions-only recovery step, and the real chunk schema field names.

Full Changelog: v1.5.0...v1.6.0

v1.5.0

Stops the shared download cache from growing without bound. Source videos are cached at ~/.cache/analyze-video/downloads/ and reused across runs; this release makes that cache self-managing and adds a manual clear.

Added

• Self-managing download cache. At the end of each run, process.py evicts cached downloads older than 14 days and trims the cache back under 5 GB total (least-recently-used first). It never removes the download the current run depends on, or one a concurrent run holds via an .in_use lease. Tune the limits with ANALYZE_VIDEO_CACHE_MAX_AGE_DAYS and ANALYZE_VIDEO_CACHE_MAX_GB (set either to 0 to disable that limit).
• Manual cache clear. python3 scripts/setup.py --clear-cache wipes cached downloads and reports how much space it freed, while leaving the docx module cache intact and skipping anything an in-progress analysis is using. setup.py --json now reports the current cache size as download_cache_bytes.

Safety

• Cache maintenance is intentionally strict: it only ever deletes directories directly under the downloads cache whose names are 16-character hex cache keys, and refuses to operate if that path is a symlink, so unrelated data (including the sibling docx node_modules cache) is never at risk.

Full Changelog: v1.4.0...v1.5.0

v1.4.0

Robustness fixes for constrained and sandboxed environments, driven by a batch of real-world run reports. Adds a constrained-Linux integration test so these seams are caught in CI.

Added

• PATH-robust tool resolution. A shared resolve_tool() finds ffmpeg, ffprobe, and yt-dlp even when they live in a user-local bin (~/.local/bin, the Python userbase) that isn't on PATH, and the pipeline now invokes them by absolute path. This fixes "tool installed but invisible" failures after pip install --user or pipx.
• Auto-install on Linux. setup.py now runs the no-sudo installs itself: yt-dlp via pipx/pip --user (with a PEP 668 --break-system-packages fallback), and the docx npm module into the per-user cache. It prints exact export PATH=... hints when a tool lands off PATH, and prints sudo hints only for packages that need root (ffmpeg, Node.js/npm).
• Constrained-environment integration test. A new CI job makes the skill directory read-only, runs the real pipeline on a synthetic local video, and builds the document, asserting docx self-installs into the writable cache. This catches environment seams that mocked unit tests can't.

Changed

• docx installs into the per-user cache when the skill dir is read-only. setup.py installs docx into ~/.cache/analyze-video (matching build-docx.js) when scripts/ isn't writable, instead of silently failing against a read-only mount.
• Compact contact-sheet appendix. Contact sheets in the document appendix are now sized so about two fit per page, instead of one sheet filling a whole page.
• Hardened delivery gate. SKILL.md Step 8 now makes the "include contact sheets / transcript?" question a mandatory, explicit gate before the single document build, so appendices are never added without asking.

Docs

• SKILL.md documents skill-directory resolution when CLAUDE_SKILL_DIR is unset, the setup exit-code contract (0 means ready, non-zero means not ready), and the harmless yt-dlp "no JavaScript runtime" warning.

Full Changelog: v1.3.0...v1.4.0

v1.3.0

This release makes the finished document self-documenting and gives you control over the contact sheets and transcript.

Added

• Source recorded in the document. Each video's analysis shows a readable "Source:" line (the original URL or local path) right under its title, so the document records exactly what was analyzed.
• Standalone transcript file. When a transcript is available, the pipeline writes a human-readable transcript.txt ([mm:ss] text per line) and exposes its location in the manifest.
• Optional transcript appendix. The document builder can append the full transcript, reading the transcript.txt directly by path so long transcripts don't bloat anything.
• Keep-artifacts options at delivery. You can now choose to include the contact sheet(s) and/or the full transcript as in-document appendices, and to keep standalone copies (clearly named, collision-safe) next to the finished document even when the working files are cleaned up.

Full Changelog: v1.2.1...v1.3.0

v1.2.1

A small follow-up to v1.1.0 focused on how the output document is named.

Added

• Title-based output naming. The produced Word document is now named after the video(s) analyzed plus the word "analysis" (for example how-to-bake-bread-analysis.docx) instead of a generic output.docx. process.py emits a ready-made, slug-safe suggested_docx_name in the manifest (falling back to the source's basename when a title isn't available, and always ending in -analysis.docx), and the builder uses it, including a combined name for multi-video documents.

Full Changelog: v1.1.0...v1.2.1

v1.1.0

Reliability fixes for long videos in sandboxed environments, a shared download cache, and a new 2-up document layout. Driven by a second real-world run report.

Fixed

• Resume no longer crashes with PermissionError after a timeout. Frames now extract into a signature-keyed subdirectory (chunks/chunk_N/frames/<sig>/), so a re-run never has to delete a prior run's files: identical configs are overwritten by ffmpeg, different configs use a fresh directory. Long videos that auto-chunk can finally resume across timeouts.
• Honest docx detection in setup. setup.py now checks every location the builder actually uses (DOCX_NODE_MODULES, NODE_PATH, scripts/node_modules, the per-user cache, and Node's default resolution) and prints a "docx pending" note instead of implying readiness when it can't be found.
• Stale subtitle / info.json artifacts are cleared before each re-download so they can't be paired with a freshly downloaded video.

Added

• Shared per-URL download cache (~/.cache/analyze-video/downloads/<url-hash>/): the full video is downloaded once and reused across runs, so a focused --start/--end rerun (even in a different out-dir) doesn't re-download everything. Timestamps stay correct. Opt out with --no-download-cache; refresh with --force.
• 2-up document layout: a frame_layout spec field ("1up" default, or "2up" for borderless side-by-side pairs), settable at the spec, video, or section level. Captions and required alt text are preserved in both layouts.
• Interrupted-run visibility: status.json records the in-flight current_chunk and a resume_hint, and chunked runs print a re-run-to-resume note.

Full Changelog: v1.0.0...v1.1.0

v1.0.0: first stable release

First stable release. A reliability, resume, and real-world failure-handling overhaul driven by a production run report.

Highlights

• Resume support. Frame extraction skips re-work when a chunk's frames already exist and the source video plus settings are unchanged (signature-based). Long videos no longer time out and restart from zero. Use --force to re-extract.
• Local sidecar pickup. A co-located subtitle (<video>.en.vtt / <video>.*.vtt / a lone paired .vtt) and <video>.info.json are now used for captions, title, uploader, and source URL when analyzing a local file.
• Trailing promo/outro trimming. New opt-in --trim-static-outro detects repeated end cards and static outros and trims them, but only for high-confidence detections so quiet legitimate endings are reported, never silently dropped.
• Failure visibility. A per-stage status.json and a rolling manifest_partial.json (removed on success) mean a run killed by a timeout is no longer a black box.
• Read-only docx fix. build-docx.js resolves the docx module across DOCX_NODE_MODULES, NODE_PATH, scripts/node_modules, and ~/.cache/analyze-video, fixing silent EACCES failures in read-only skill directories.
• Contact-sheet appendix. Optionally append the chunk contact sheets to the generated Word doc as a visual appendix.

Fixed

• Local files no longer lose their subtitle or report the bare filename as the title.
• Frame extraction no longer wipes and re-extracts every chunk on each run.

Full Changelog: v0.4.0...v1.0.0