c64cast 0.1.0__tar.gz

c64cast-0.1.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+All notable changes to c64cast are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and c64cast follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) over its *user*
+surface — the CLI flags, the config schema, the `example:` names, and the data
+directory layout. The Python API carries no stability promise while the version
+is `0.x`.
+
+Work lands under `## [Unreleased]`; cutting a release renames that section to
+the version and stamps it with the date.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-07-30
+
+The first public release. c64cast has been in daily use against real hardware
+since June 2026 — this is the point where it becomes installable rather than
+cloneable.
+
+### Added
+
+**Two hardware backends, selected by URI.** `-u u64://HOST` (or `http(s)://`)
+drives an [Ultimate 64](https://ultimate64.com/), Ultimate II+, or Commodore 64
+Ultimate: memory writes go over the Ultimate DMA Service on TCP port 64 with
+REST for the handful of operations that have no DMA equivalent. `-u tr://`
+drives a [TeensyROM+](https://lectronz.com/products/teensyrom) cartridge in an
+original C64 over auto-detected USB serial, an explicit serial device
+(`tr:///dev/cu.usbmodemXYZ`, `tr://COM3`), or raw TCP (`tr://HOST[:PORT]`).
+Per-link knobs ride along as query parameters (`u64://host?dma_port=64`,
+`tr:///dev/…?baud=2000000`). `$C64CAST_URL` is the environment fallback.
+
+**Ten scene types**, mixed freely in a TOML playlist with per-scene durations
+and an "UP NEXT" interstitial between them:
+
+- **video** — MP4/MKV/etc. with its soundtrack, paced off the audio clock so
+  A/V cannot drift. YouTube and other streaming URLs resolve through yt-dlp.
+- **webcam** — live capture quantized to any display mode in real time.
+- **slideshow** — still images from a directory or glob, aspect-fit.
+- **waveform** — plays a `.sid` on the real chip through a small player PRG
+  DMA'd into C64 RAM (deliberately not the firmware's own runner, which
+  hijacks the HDMI output), with a 3-voice oscilloscope driven by a host-side
+  py65 SID emulator. Handles multi-SID tunes up to 8 chips on the U64's
+  UltiSIDs, and matches 6581/8580 tunes to the installed chips.
+- **midi** — bridge a live MIDI source into the real SID and scope each voice.
+- **asid** — receive an ASID stream (DeepSID in a browser, SIDFactory II,
+  Plogue chipsynth C64) and play it on the real SID with the same scope.
+- **generative** — 20 procedural sources (plasma, tunnel, fire, mandelbrot,
+  metaballs, game of life, fireworks, soap, …), optionally music-reactive.
+- **launcher** — hand the machine over to a native `.prg`/`.crt` and reclaim it.
+- **wled** — turn the C64 into a virtual LED matrix fed by a realtime pixel
+  stream from LedFx or xLights (DDP or WLED realtime UDP).
+- **blank** — a solid PETSCII canvas as a foundation for overlays.
+
+**Six VIC-II display modes** — `petscii`, `mcm`, `hires`, `hires_edges`,
+`mhires`, `blank` — each with its own vectorized quantizer (≈30 fps bitmap,
+50/60 fps character modes over a LAN). The `[color]` pipeline shapes any source
+before quantization: spatial dithering, perceptual color matching, per-cell
+strategy selection, motion smoothing, scene fades, and a forced-palette mode
+that remaps a frame onto a chosen subset of the 16 C64 colors — with a rolling
+palette that re-clusters as the content changes. `--suggest-palette FILE`
+analyzes an image or video and ranks the colors that represent it most
+faithfully.
+
+**Audio on the real SID.** By default, video and file audio play through the
+U64's Ultimate Audio FPGA PCM sampler for high fidelity; the lo-fi `$D418` DAC
+path (4-bit, or ≈6–7 bit via Mahoney companding) covers TeensyROM+, mic input,
+and webcam audio everywhere. The sampler's effective clock ships calibrated, so
+audio holds sync against host-paced video over long runs. `--calibrate-dac`
+measures a per-machine DAC response curve through an HDMI capture device.
+
+**Thirteen stackable overlays** — `scrolling_text`, `marquee`, `rss`,
+`spectrum_petscii`, `spectrum_bitmap`, `clock`, `weather`, `callsign`,
+`countdown`, `network`, `logo`, `big_text`, `obs_status` — composable onto any
+compatible scene, with `--compat` printing the overlay × display-mode matrix.
+
+**Ensemble mode.** One process drives N systems at once as a video wall, with
+cross-system orchestration — a `big_text` message scrolling across every screen
+as one continuous canvas, spans and mirrors — and audio-slot coordination so
+the systems do not fight over the DAC.
+
+**Live control surfaces.** The C64's own keyboard (C= pauses, CTRL skips, SHIFT
+cycles the display style), an on-C64 menu for live scene tweaks, webcam hand
+gestures, a FastAPI control plane (`/pause`, `/resume`, `/skip`, `/reload`),
+MIDI CC mapped to any live parameter, and `SIGHUP` to reload the config. The
+DJ/VJ layer adds a tempo/beat grid, a clip-launch grid with LED feedback on
+grid controllers, a layerable chain of 8 pixel effects, snapshot-recall of
+"looks", and a phone/web performance console.
+
+**WLED bridge**, in three directions under one `[wled]` section: drive real LED
+matrices *from* the C64's SID with no microphone, present c64cast *as* a virtual
+WLED device that the WLED app and Home Assistant discover and control, and turn
+the C64 *into* a matrix that LedFx/xLights stream pixels to.
+
+**Quick playback.** `c64cast clip.mp4 tune.sid pics/ 'https://youtu.be/…'`
+plays media straight from the command line with no config file, mapping each
+argument to the right scene type by extension.
+
+**Config authoring and discovery, all offline.** An annotated TOML reference,
+an interactive wizard (`--init`), and a JSON Schema for editor autocomplete —
+plus `--describe`, `--list-scenes`, `--list-overlays`, `--list-modes`,
+`--compat`, and `--print-schema`, all generated from the same field metadata the
+loader itself runs on, so they cannot drift from the code. `--doctor` collects
+every config and environment problem in one pass. Machine-local defaults live in
+`~/.config/c64cast/settings.toml` (written by `--save-settings`) and persisted
+state in `~/.local/share/c64cast/`, both XDG-aware.
+
+**Packaged demo configs.** Every feature has a runnable single-scene demo
+shipped inside the wheel: `--config example:NAME` runs one, `--list-examples`
+lists them all, `--print-example NAME` copies one out to edit.
+
+**Preview and recording.** An optional local window mirroring what the C64 is
+showing, and recording the same to MP4. Both are cv2-based, so neither needs an
+optional dependency.
+
+**Documentation.** A typeset User's Guide (10 chapters), a full config
+reference, symptom-first troubleshooting, an extension guide, and per-module
+architecture notes covering the hardware constraints and the dead ends behind
+each design decision. Every install instruction and every missing-extra hint
+names `uv`; `pipx` is documented once as an equivalent fallback.
+
+The guide is attached to every release as a PDF, stamped on its cover with the
+version it documents, so a downloaded copy can always be matched to the install
+it describes. `make guide` renders the same thing from a checkout.
+
+A config written by `--init` or `--save-settings` carries a `#:schema`
+directive pinned to its own release, so an editor validates it against the
+schema this version actually accepts rather than whatever is currently on
+`main`.
+
+**A leading `~` works in config-file paths.** `file`, `videos_dir`,
+`songlengths_file`, `charset_path`, `model_path`, a `logo` overlay's file, the
+recording path and `log_file` all expand `~/…` when they are used. A TOML file
+has no shell to do it, and `glob`/`os.path` treat `~` as a literal directory
+name, so such a path previously matched nothing. A `Config` still holds the
+string as written, so serialized configs keep the `~` rather than baking in an
+absolute home directory.
+
+**Windows is a supported platform.** It always worked — casting to a real
+Commodore from Windows is a routine path for one of the contributors — but the
+published metadata and the User's Guide both called it untested, because CI only
+ever ran on Linux. The test matrix now covers macOS, Linux and Windows across
+Python 3.11–3.14, so the claim is backed on both halves: the matrix for the
+host-side code, real hardware for the pipeline. The one platform difference worth
+knowing is that `SIGHUP` config reload is POSIX-only; `POST /reload` on the
+control plane does the same thing everywhere.
+
+[Unreleased]: https://github.com/kfox/c64cast/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kfox/c64cast/releases/tag/v0.1.0

c64cast-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**c64cast@gmail.com**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

c64cast-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to c64cast
+
+Bug reports, feature ideas, and pull requests are all welcome. This file covers
+the development setup and the conventions the repo follows. If you only want to
+*use* c64cast, the [README](README.md) has what you need — you do not need any
+of this.
+
+Security issues go through [SECURITY.md](SECURITY.md), not a public issue.
+Everyone participating is expected to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+c64cast uses the [uv](https://github.com/astral-sh/uv) project workflow.
+
+```bash
+git clone https://github.com/kfox/c64cast
+cd c64cast
+uv sync --all-extras    # creates/updates .venv from uv.lock: every runtime
+                        # extra + the dev tool group
+pre-commit install      # ruff + pyright + tests run before every commit
+```
+
+Then either prefix one-off commands with `uv run`, or let
+[direnv](https://direnv.net/) activate `.venv` for you — `.envrc` is gitignored,
+so write your own with `layout uv` in it (plus `use mise` if you use mise, and
+an `export C64CAST_URL=…` so you can drop `-u` while developing).
+The maintainer's setup is mise + direnv + uv; none of that is
+required, but `uv` itself effectively is — `uv.lock` is the reproducible
+definition of the environment CI runs.
+
+> [!IMPORTANT]
+> **Do not use `uv pip install -e .[...]` in this repo.** mise sets
+> `UV_PYTHON` to the bare toolchain interpreter, and `uv pip` honors that over
+> the active `.venv` — so packages land in the mise install while
+> `python -m c64cast` runs from `.venv`. The symptom is a silent
+> "PyAV unavailable" or a missing extra that you just installed.
+> `uv sync` and `uv run` target the project environment and are immune.
+>
+> Note also that `dev` is a PEP 735 dependency *group*, not an extra, so
+> `.[all,dev]` can never resolve it no matter which installer you use. With
+> plain pip: `pip install -e .[all] && pip install --group dev`.
+
+If you use VS Code, point the interpreter at `.venv/bin/python` rather than the
+mise interpreter, or editor diagnostics will diverge from what actually runs.
+
+`make doctor` is the fast offline self-check for all of the above: it reports the
+c64cast version, flags a wrong interpreter, a hard dependency that will not
+import, and `uv.lock` drift, before any of those cost you a debugging session.
+
+## Running from a checkout
+
+```bash
+python -m c64cast --config example:hello -u u64://192.168.2.64
+```
+
+[`scripts/c64cast.sh`](scripts/c64cast.sh) is an equivalent launcher that `cd`s
+to the repo root and forwards every argument, running through `uv run` when `uv`
+is on `PATH` (so the project `.venv` is always used) and falling back to a bare
+`python` otherwise. Use it from another directory, or from a context where
+direnv has not activated `.venv` — cron, systemd, an ssh one-liner:
+
+```bash
+scripts/c64cast.sh --config example:hello
+scripts/c64cast.sh --doctor --skip-probe
+```
+
+## The pre-PR gate
+
+```bash
+make check      # lint + typecheck + test — run this before opening a PR
+```
+
+Every target routes through `uv run`, so they hit the synced project env
+whether or not the current shell has `.venv` activated:
+
+| Target | What it does |
+|---|---|
+| `make sync` | `uv sync --all-extras` (refresh the project env) |
+| `make lint` | `ruff check` |
+| `make fmt` | `ruff format` |
+| `make test` | the unittest suite, parallel across cores (`T=tests.test_foo` runs just that, serially) |
+| `make coverage` | tests under coverage → report + HTML + `coverage.xml` + JUnit XML |
+| `make typecheck` | `mypy --strict` on the state-bearing modules + `pyright` across the tree |
+| `make doctor` | offline environment + config diagnostics |
+| `make schema` | regenerate `c64cast/data/c64cast.schema.json` from the config metadata |
+| `make guide` | render the User's Guide to a typeset PDF (needs `typst`) |
+| `make bench` | the async write-pipeline benchmark |
+
+CI runs the same lint, typecheck, and tests on every push and pull request
+across Python 3.11–3.14 — see
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml). Type-checking is
+deliberately two-tiered: `pyright` in basic mode across the whole tree
+(including tests), matching Pylance's VS Code defaults so editor diagnostics
+align with CI, plus `mypy --strict` on the state-bearing modules listed in
+`[tool.mypy] files` where a type slip would corrupt state.
+
+## Tests
+
+The suite is stdlib `unittest`, one module per subject under `tests/`, and it
+runs entirely without hardware — the hardware backends are faked. A test run
+should print **only** pass/fail/skip indicators: wrap any path that raises an
+expected exception in `assertRaises`, any path that logs an expected
+warning/error in `self.assertLogs("c64cast.<module>", …)`, and any path that
+writes to stdout in a `redirect_stdout`. Expected output left to print buries
+real failures. When a call both logs and raises, nest `assertLogs` *outside*
+`assertRaises` so the records are actually verified.
+
+Several tests exist purely to stop documentation from drifting — the JSON schema
+against the config metadata, the annotated example TOML against the dataclass
+fields, the `all` extra against the union of the other extras. If one of those
+fails, the fix is usually to regenerate rather than to edit the test.
+
+## Hardware for development
+
+An HDMI capture device (Elgato Cam Link 4K, Genki ShadowCast, …) is highly
+recommended: a RAM dump cannot prove what the VIC-II actually drew, so visual
+changes need a capture to verify. [`scripts/diags/`](scripts/diags) holds the
+committed diagnostic tooling that drives one — a U64 REST/DMA probe, HDMI still
+capture, audio capture with level analysis, and a launch-capture-reset harness.
+Improve those rather than writing fresh throwaway scripts.
+
+If you touch the hardware paths, leave every machine you tested against silent
+and reset when you are done.
+
+## Commits and pull requests
+
+- **Conventional commits**: `feat(scope): …`, `fix(scope): …`, plus `docs`,
+  `build`, `test`, `refactor`, `perf`, `chore`, `ci`. The subject is a lowercase
+  imperative phrase. The changelog is written from this history, so a subject
+  line that reads as a user-visible statement is worth the extra few seconds.
+- **One logical change per commit**, and per PR. Unrelated cleanup goes in its
+  own commit.
+- **Work on a branch and open a PR** — `main` is protected by CI and every
+  change lands through review.
+- `make check` must be green before you open the PR.
+- Do not commit user media, personal configs, or machine-specific details (IP
+  addresses, capture-device names, local paths). `assets/` tracks only its
+  per-directory READMEs by design; everything else there is gitignored.
+
+## Documentation is part of the change
+
+A behavior change updates its documentation **in the same change set** — not in
+a follow-up. Concretely, when you change functionality:
+
+- [`docs/architecture.md`](docs/architecture.md) and the topic notes under
+  [`docs/architecture/`](docs/architecture) carry the *why* for each module:
+  design rationale, hardware constraints, and the dead ends that the code alone
+  does not show. Read the relevant section before modifying a module, and update
+  it in the same PR. The index's module table routes any module to its section.
+- [`docs/usage.md`](docs/usage.md), [`caveats.md`](docs/caveats.md),
+  [`troubleshooting.md`](docs/troubleshooting.md), and
+  [`extending.md`](docs/extending.md) cover the user-facing surface.
+- New config knobs, scenes, or overlays: fill in the field's `help`/`choices`
+  metadata (in [`c64cast/config.py`](c64cast/config.py)) or the overlay's
+  `HELP`/`PARAM_HELP`, update
+  [`c64cast/examples/c64cast.example.toml`](c64cast/examples/c64cast.example.toml)
+  and add a demo under [`c64cast/examples/`](c64cast/examples), then run
+  `make schema`. That single metadata model drives `--describe`, `--list-*`,
+  `--compat`, the JSON schema, the config serializer, and the `--init` wizard,
+  so filling it in is what keeps all of them from drifting — and the drift tests
+  will tell you if you skipped it.
+- Add `CHANGELOG.md` entries under `## [Unreleased]` for anything users would
+  notice.
+- Hand-encoded 6502 bytes (the NMI DAC handler, the REU pump, the SID player
+  PRG, BASIC stubs) are annotated with the assembly they represent and why each
+  instruction is there. Keep that up when you touch a byte array — a wall of hex
+  is not reviewable.
+- Write documentation in the present tense, describing what the code does now.
+  It is not a record of what changed; that is what the changelog and git history
+  are for.
+
+[`docs/extending.md`](docs/extending.md) is the starting point for adding a new
+Scene, Overlay, DisplayMode, or interstitial Background.
+
+## What counts as a breaking change
+
+c64cast's stable surface is the part users depend on: the **CLI flags**, the
+**config schema**, the **`example:` names**, and the **data directory layout**.
+Removing or renaming any of those needs a deprecation warning for one minor
+release first. The Python API carries no stability promise while the version is
+`0.x` — internal modules may be reshaped freely, as long as the four surfaces
+above keep working.
+
+Cutting a release is a maintainer task and lives in
+[`RELEASING.md`](RELEASING.md). The one thing worth knowing as a contributor is
+that the `## [Unreleased]` section of the changelog becomes the release notes
+verbatim, so write an entry as the announcement it will be.

c64cast-0.1.0/LICENSE

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

c64cast-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+# Extra top-level files for the source distribution.
+#
+# setuptools puts README.md (via `readme`), LICENSE (via `license-files`),
+# pyproject.toml, and everything under the package into the sdist on its own.
+# These are project-level documents rather than package data, so they need
+# naming here or the source archive ships without them — and a source archive
+# with no changelog is the one thing people go looking for when they download
+# one. The wheel is unaffected; package data lives in
+# [tool.setuptools.package-data] instead.
+include CHANGELOG.md
+include CONTRIBUTING.md
+include RELEASING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md