muvid 0.0.2__tar.gz

muvid-0.0.2/.claude/skills/mtv/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: mtv
+description: Use when the user wants to make a music video from a song. Triggers on "make a music video", "turn this song into a video", "/mtv", or any work inside an mtv project folder (look for project.json with mtv schema_version). Walks the user through getting lyrics, aligning to audio, casting characters, picking environments, writing the script, and rendering shots.
+---
+
+# mtv — guide a user from song to music video
+
+You are operating an `mtv` project: a folder containing a `project.json`,
+a song under `song/`, and progressively-filled-in artifacts under
+`lyrics/`, `characters/`, `environments/`, `script/`, `shots/`,
+`output/`. The Python package `mtv` exposes every step as a function;
+the CLI `mtv <verb>` is a thin dispatcher.
+
+Your job is to **drive that pipeline interactively** — pick the right
+next step based on the project's current state, run the command, show
+the user what came out, and ask just enough questions to keep moving.
+
+## The pipeline (eight stages, each idempotent)
+
+1. **init** — `mtv init <root> --song <audio>`. Fresh project, song
+   probed.
+2. **transcribe** — `mtv transcribe <root>`. ElevenLabs Scribe writes
+   `lyrics/transcript.json` and a draft `lyrics/lyrics.md`.
+3. **edit lyrics** — *user task*. The user opens `lyrics/lyrics.md`,
+   fixes mishears (singing transcripts always have some), and adds
+   real `[section]` headers like `[verse 1]`, `[chorus]`, `[bridge]`.
+4. **align** — `mtv align <root>`. Builds `lyrics/alignment.annot` (a
+   `lacing` SqliteStore) with three tiers: sections / lines / words.
+   Also syncs the parsed sections into `project.json`.
+5. **cast characters** — for each character:
+   - `mtv character <root> <name> --description "..."`
+   - `mtv character-images <root> <name> path1 path2 ...` (drop user
+     photos) or `mtv character-generate <root> <name> --n 6` (use fal
+     to generate variants).
+   - `mtv character-curate <root> <name> --k 8` (lookbook picks the
+     best diverse subset).
+6. **establish environments** — `mtv environment <root> <name>
+   --description "..." --time-of-day "..."` then
+   `mtv environment-render <root> <name>`.
+7. **write the script** — author `script/script.md` (you can draft this
+   from lyrics + characters + environments; the user edits). Then
+   `mtv script-apply <root>` to upsert sections+shots into the SSOT.
+8. **render** — `mtv render <root>` (all shots) or `mtv render <root>
+   --shot s02`. Per-shot strategies: `lipsync`, `image_to_video`,
+   `text_to_video`, `animation`, `still`.
+9. **compose** — `mtv compose <root>`. Concatenates shots, overlays
+   the original song.
+
+## Always start by reading state
+
+Before doing anything, run `mtv status <root>` to see where the user
+is. The output is a JSON dict; pick the next stage where a flag is
+False or a count is zero. **Never** re-run a stage that's already
+done unless the user asks — every stage is idempotent but they cost
+API calls (Scribe, fal).
+
+## Lyric editing — the part that needs you most
+
+Step 3 (editing `lyrics/lyrics.md`) is the highest-leverage human
+input. The format:
+
+```
+[intro]
+(instrumental)
+
+[verse 1]
+I came down to the river       // 12.5
+to wash my soul                // 16.2
+
+[chorus]
+hold my hand
+when the night comes calling
+```
+
+- `[label]` headers tag sections. Use what fits the song
+  (intro/verse/chorus/bridge/outro/breakdown/etc.).
+- `(parenthesized)` lines are non-vocal placeholders.
+- `// 12.5` after a line is an optional manual start anchor in
+  seconds. Useful for sections where Scribe got the timing wrong;
+  not required.
+- The order of lines must match the song.
+
+After editing, run `mtv align` and read the resulting alignment
+quickly: lines whose `start_s` look obviously wrong (out of order,
+or in the middle of an instrumental break) are usually mishears
+that need a fix. Re-edit, re-align.
+
+> **Background**: the trade-offs around different alignment
+> approaches (Scribe + greedy match vs. WhisperX CTC vs. singing-grade
+> systems like STARS) are summarized in
+> `misc/docs/alignment_references.md`. v0 deliberately uses the
+> cheapest path because the user is the source of truth for the
+> lyric text anyway.
+
+## Choosing render strategies
+
+For each shot, pick:
+
+- `lipsync` — character is singing on screen. Needs a curated
+  character image. Calls `falaw.animate_face` (image+audio →
+  talking-head). Best for verses/choruses with the singer in frame.
+- `image_to_video` — cinematic shot. Uses the environment image as
+  the i2v seed (or generates a fresh storyboard still). Great for
+  intro/outro establishing shots and instrumental passages.
+- `text_to_video` — pure prompt → video, no anchor image. Use
+  sparingly (no character/location consistency).
+- `animation` — hand off to the `an` package for stylized 2D cutout
+  animation. Best for lyric-video passages or surreal sequences.
+- `still` — single image held for the duration. Cheapest. Good for
+  title cards, transitions.
+
+When proposing a script, default to a sensible mix:
+- 1 establishing `image_to_video` per major section
+- `lipsync` for verses/chorus when a character is featured
+- `still` or `animation` for short bridges and outros
+
+## When you draft the script for the user
+
+Read the project: `mtv status`, then read `lyrics/lyrics.md`,
+character cards (`characters/<name>/card.json`), environment cards
+(`environments/<name>/card.json`). Write `script/script.md` in this
+shape:
+
+```markdown
+# <project title> — script
+
+## [intro] 0.00 → 12.50
+
+### s01 | 0.00-12.50 | image_to_video
+**env**: park_bench  **camera**: slow push-in
+A wide of the empty park bench at golden hour. Leaves drifting.
+
+## [verse 1] 12.50 → 35.00
+
+### s02 | 12.50-22.00 | lipsync
+**env**: park_bench  **chars**: maya
+Medium close on Maya. She begins to sing, looking off-camera.
+
+### s03 | 22.00-35.00 | image_to_video
+**env**: park_bench  **chars**: maya
+Push in to a tight close-up. She closes her eyes on the last word.
+```
+
+Rules:
+- Shot ids are `s01`, `s02`, ... in timeline order.
+- Each shot's `[start-end]` MUST fit inside the section that contains
+  it. Shots within a section MUST cover its span without gaps or
+  overlap (or there will be silent / black gaps in the final video).
+- Never propose a `lipsync` shot that doesn't reference a character
+  with at least one curated image — check before suggesting it.
+
+After writing the markdown, **show the user the diff** (or just the
+content) and ask "edit anything before I apply this?" before running
+`mtv script-apply`.
+
+## Render walk
+
+When the user says "render it", default to:
+1. Confirm with `mtv status` that all stages 1–7 are done.
+2. Render shot-by-shot (`mtv render --shot s01`, then `s02`, ...) so
+   if one fails the others aren't lost. Show the user each output as
+   it lands.
+3. After all shots succeed: `mtv compose`.
+4. Print the final mp4 path and recommend they open it.
+
+If a shot's render strategy fails (fal API error, no character
+image), explain the failure and offer the smallest fix (different
+strategy, generate the missing image, etc.) — don't just retry.
+
+## Things to never do
+
+- Never re-run `mtv transcribe` after the user has edited
+  `lyrics/lyrics.md` — it would clobber the transcript that the
+  alignment depends on. (The lyrics.md only gets clobbered if it
+  doesn't already exist, but transcript.json gets overwritten.)
+- Never auto-edit `lyrics/lyrics.md`. The user is the source of
+  truth for what the song actually says.
+- Never call `mtv render` with `--force` unless the user explicitly
+  asks; renders cost real money on fal.
+- Never compose before all shots have rendered outputs.
+
+## Useful inspection commands
+
+- `mtv status <root>` — overview JSON.
+- `cat <root>/project.json | jq` — the SSOT.
+- `cat <root>/lyrics/lyrics.md` — the user's lyrics.
+- `ls <root>/shots/` — see which shots have been rendered (each one
+  is a folder with `output.mp4` if done).
+- `cat <root>/.mtv/decisions.jsonl` — append-only log of every
+  pipeline action.
+
+## When the user starts from scratch
+
+If the user just says "make a music video from `~/Downloads/song.mp3`"
+and there's no project yet:
+
+1. Pick a sensible project root (ask if unsure). Default to
+   `~/mtv/<song-stem>`.
+2. `mtv init <root> --song <path>` — show the resulting folder.
+3. `mtv transcribe <root>` — show the draft `lyrics.md`.
+4. Pause. Tell the user: "Open `<root>/lyrics/lyrics.md`, fix any
+   mishears, and add real section tags. Tell me when it's done."
+5. When they confirm, `mtv align <root>` → show them how many
+   sections/lines/words got aligned.
+6. Walk them through casting (one character at a time), then
+   environments, then drafting the script, then rendering.
+
+Move at the user's pace; offer the next step but never run more
+than one stage of the pipeline without checking in.

muvid-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

muvid-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,209 @@
+name: Continuous Integration (uv)
+on: [push, pull_request]
+
+# Note: Environment variables (PROJECT_NAME and vars from [tool.wads.ci.env])
+# are set by the read-ci-config action in the setup job and made available
+# to all subsequent jobs via GITHUB_ENV
+
+jobs:
+  # First job: Read configuration from pyproject.toml
+  setup:
+    name: Read Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      project-name: ${{ steps.config.outputs.project-name }}
+      python-versions: ${{ steps.config.outputs.python-versions }}
+      pytest-args: ${{ steps.config.outputs.pytest-args }}
+      coverage-enabled: ${{ steps.config.outputs.coverage-enabled }}
+      exclude-paths: ${{ steps.config.outputs.exclude-paths }}
+      test-on-windows: ${{ steps.config.outputs.test-on-windows }}
+      build-sdist: ${{ steps.config.outputs.build-sdist }}
+      build-wheel: ${{ steps.config.outputs.build-wheel }}
+      metrics-enabled: ${{ steps.config.outputs.metrics-enabled }}
+      metrics-config-path: ${{ steps.config.outputs.metrics-config-path }}
+      metrics-storage-branch: ${{ steps.config.outputs.metrics-storage-branch }}
+      metrics-python-version: ${{ steps.config.outputs.metrics-python-version }}
+      metrics-force-run: ${{ steps.config.outputs.metrics-force-run }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Read CI Config
+        id: config
+        uses: i2mint/wads/actions/read-ci-config@master
+        with:
+          pyproject-path: .
+
+  # Second job: Validation using the config
+  validation:
+    name: Validation
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    needs: setup
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.setup.outputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps-uv@master
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Lint Validation
+        run: uvx ruff check --output-format=github ${{ needs.setup.outputs.project-name }}
+
+      - name: Run Tests
+        uses: i2mint/wads/actions/run-tests-uv@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+          pytest-args: ${{ needs.setup.outputs.pytest-args }}
+          exclude-paths: ${{ needs.setup.outputs.exclude-paths }}
+          coverage: ${{ needs.setup.outputs.coverage-enabled }}
+
+      - name: Track Code Metrics
+        if: needs.setup.outputs.metrics-enabled == 'true'
+        uses: i2mint/umpyre/actions/track-metrics@master
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: ${{ needs.setup.outputs.metrics-config-path }}
+          storage-branch: ${{ needs.setup.outputs.metrics-storage-branch }}
+          python-version: ${{ needs.setup.outputs.metrics-python-version }}
+          force-run: ${{ needs.setup.outputs.metrics-force-run }}
+
+  # Optional Windows testing (if enabled in config)
+  windows-validation:
+    name: Windows Tests
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && needs.setup.outputs.test-on-windows == 'true'"
+    needs: setup
+    runs-on: windows-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps-uv@master
+
+      - name: Run Tests
+        uses: i2mint/wads/actions/run-tests-uv@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+          pytest-args: ${{ needs.setup.outputs.pytest-args }}
+          exclude-paths: ${{ needs.setup.outputs.exclude-paths }}
+
+  # Publishing job
+  publish:
+    name: Publish
+    permissions:
+      contents: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')"
+    needs: [setup, validation]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: i2mint/wads/actions/setup-python-uv@master
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+          create-venv: "false"
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Update Version Number
+        id: version
+        uses: i2mint/isee/actions/bump-version-number@master
+
+      - name: Build Distribution
+        uses: i2mint/wads/actions/build-dist-uv@master
+        with:
+          sdist: ${{ needs.setup.outputs.build-sdist }}
+          wheel: ${{ needs.setup.outputs.build-wheel }}
+
+      - name: Publish to PyPI
+        uses: i2mint/wads/actions/pypi-publish-uv@master
+        with:
+          pypi-token: ${{ secrets.PYPI_PASSWORD }}
+
+      - name: Force SSH for git remote
+        run: git remote set-url origin git@github.com:${{ github.repository }}.git
+
+      - name: Commit Changes
+        uses: i2mint/wads/actions/git-commit@master
+        with:
+          commit-message: "**CI** Formatted code + Updated version to ${{ env.VERSION }} [skip ci]"
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+          push: true
+
+      - name: Tag Repository
+        uses: i2mint/wads/actions/git-tag@master
+        with:
+          tag: ${{ env.VERSION }}
+          message: "Release version ${{ env.VERSION }}"
+          push: true
+
+  # Optional GitHub Pages
+  github-pages:
+    name: Publish GitHub Pages
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: i2mint/epythet/actions/publish-github-pages@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          ignore: "tests/,scrap/,examples/"

muvid-0.0.2/.gitignore

@@ -0,0 +1,117 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

muvid-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.