c64cast v0.2.0

Downloads

• 📘 c64cast User's Guide 0.2.0 (PDF)
  — 10 chapters, read in order, starting from nothing.
• 📕 c64cast Programmer's Reference Guide 0.2.0 (PDF)
  — every scene, knob and register, with nine generated appendices.
• 🎛️ c64cast Performance Card 0.2.0 (PDF)
  — two pages for the desk next to the controller.
• 📦 c64cast-0.2.0-py3-none-any.whl
  · c64cast-0.2.0.tar.gz
  — or just uv tool install 'c64cast[all]'
  (PyPI).

---

Added

• c64cast reads the C64 character ROM off your own machine. Every glyph
  drawn as C64 text — the text overlays on bitmap modes (scrolling_text,
  marquee, corner_text, logo), big_text, the on-C64 menu, the
  oscilloscope's labels, the preview window and the stream recorder — comes from
  the character ROM. Previously the only way to have one was to find a dump and
  drop it at a working-directory-relative path in a source checkout, which meant
  an installed c64cast could never resolve it and a user report of "the
  scrolling text looks bad" was, in full, "there is no character ROM". Now the
  first run against a machine reads it off the C64 and caches it at
  <data dir>/roms/chargen.bin; every later run picks it up. It costs about a
  second, once per machine, and no ROM bytes are shipped or downloaded — they
  move from your hardware to your disk. --dump-char-rom re-reads on demand
  (after swapping in a different character ROM, say), --install-char-rom PATH
  installs a 2 KB or 4 KB dump you already have with no hardware involved, and
  [hardware].dump_char_rom = false turns the automatic read off. --doctor
  reports which ROM is in use and whether it verifies.
• A second book: the Programmer's Reference Guide (docs/reference/), the
  volume you open at the page you need rather than read in order. Seven
  chapters: the configuration language and its precedence rules, the catalog
  of every scene and overlay, the display pipeline from frame to VIC-II
  register, the sound path in both directions, the link into the Commodore's
  memory and what lands there, every input and output that reaches the show from
  outside, and how to extend the program itself. Its appendices
  are generated from the code by scripts/gen_reference_appendices.py: every
  configuration section and field, every scene key, every overlay parameter, the
  overlay against display-mode matrix, every generator and effect, every
  live-tune target, every command-line flag, every packaged example and every
  optional install extra. They
  read the same definitions that answer --describe, --compat and
  --print-schema, so a table in the book cannot disagree with the program.
  make reference renders it, make books renders every book, and make reference-appendices rewrites the generated ones — which CI checks for drift.
• A third book: the Performance Card (docs/card/), two printable pages for
  the desk beside the controller. Every control surface and what it is mapped to
  out of the box, the pad chords and pad-light states, every live-tune target,
  the clip-grid and tempo syntax, the console's routes, how a channel addresses
  one Commodore of an ensemble, and the four commands worth running before the
  doors open. make card renders it; its live-target table is generated
  alongside the reference guide's appendices. It takes the card layout: the
  same palette, faces and tables as the other two books, set two-up at 8.5pt
  with no cover, contents or chapter openers.
• The GitHub release now carries every book, each stamped with the version:
  the User's Guide, the Programmer's Reference Guide and the Performance Card.

Removed

• docs/usage.md is gone. Its 1,867 lines were the end-user reference
  before there was a book to put them in; every part of it that was not already
  duplicated by the User's Guide has been rewritten into the Programmer's
  Reference Guide, which states the same rules from the code rather than from
  prose that had drifted from it. Every link that pointed there now points at
  the chapter or appendix that answers the question, and a test fails if a new
  one appears.

Changed

• The Programmer's Reference Guide now documents what a reload actually
  re-reads, and the signals. POST /reload was described as re-reading the
  configuration and rebuilding the playlist, which overpromised: a reload swaps
  [[scenes]] and [interstitial] and nothing else — the connection, the audio
  path, the capture device and even [playlist]'s own loop and
  fade_duration_s are fixed at startup. Chapter 6 now says so, and gains a
  Signals section covering SIGHUP (the control-plane-free spelling of the
  same reload, POSIX-only, which the User's Guide advertised and the reference
  never mentioned), SIGTERM, and the ensemble rule that each system re-reads
  its own file while the master is not re-read. No behavior changed.
• The hopalong generator's live target source.a is now source.shape.
  Every other live target is named for what turning it does — drift_speed,
  ring_freq, zoom_speed — and this one was named for the letter Barry
  Martin's map gives the constant, which tells a performer looking at a knob
  label nothing. Sweeping it reshapes the attractor, so it is shape. The
  constant is still a in the implementation, where it matches the published
  map. source.a was never settable from a config; the one thing this breaks is
  a hand-written [[midi.mappings]] entry naming it, which now silently fails to
  match — rename the target.
• [preview] charset_path now defaults to unset, meaning "use the character ROM
  c64cast resolved". Set it to force a specific file. A configured path that
  doesn't exist now warns and falls back to the built-in font instead of raising
  FileNotFoundError and killing the run.
• The built-in fallback font now fills screen codes $80-$FF as the reverse-video
  complement of $00-$7F, like the real ROM. They were blank, so with no
  character ROM installed big_text's glyph pixels, the blocks PETSCII style
  and most of the PETSCII shading ramp — all of which paint $A0 and up —
  rendered as nothing.
• The User's Guide build now renders a book rather than the guide, in
  preparation for a second volume. scripts/build_guide.py is
  scripts/build_book.py --book-dir docs/<book>, the Typst template and the
  vendored OFL fonts moved from docs/guide/ to docs/shared/, and each book's
  book.toml names the layout it takes. make guide and the released PDF are
  unchanged.
• The reference guide's generated appendices are set as two columns instead of
  four. A field's name, type and default are three facts about one setting,
  and given a column each on a 6.24in page they left the description — the only
  part written for a human — about a third of the measure and four words to a
  line, with a single field running most of a page. They are now stacked into
  one fixed-width column with the description taking the rest, at the same width
  in every such table, so a scene key, an overlay parameter and a CLI flag all
  line up down the book. The reference is 20 pages shorter for it.
• Chapter and appendix cross-references are links. "See Appendix F" in the
  prose jumps to Appendix F, and every line of the table of contents jumps to
  its page. A reference to a chapter the book does not have now fails the build,
  which is what catches a renumbering the prose was not told about.
• Every section of every book can be linked at, and the chapter opener pages
  are clickable. The contents page already navigated; the opener page listed
  its sections and did nothing when you pressed one. Each ## and ### heading
  now carries an anchor, the opener bullets jump to the section they name, and
  the prose can link at a section — [Fades](04-display-pipeline.md#fades) —
  rather than only at a whole chapter, so a pointer can mean a row in a table
  instead of a page with a big numeral on it. The anchor is GitHub's own, because
  the Markdown is the book: the same link resolves on github.com and in the PDF.
  One that resolves nowhere fails the build and names the nearest ones it knows.
• The Programmer's Reference Guide has an index, and it is generated like
  its appendices. Every name the program can utter goes in — configuration
  sections and keys, command-line flags, scene types, overlays, display modes,
  generators, effects and live-tune targets — against the pages that discuss it.
  Locators are clickable page numbers in the PDF and section links on
  github.com, from the one source, because the Markdown is the book in one place
  and there are no pages in the other. A key is listed bare, and again under its
  section where two sections share the name; a parameter belonging to a
  generator, an effect or a display mode is filed under its own name with the
  holder in parentheses, so axis is where you look and axis (effect) is what
  you find. A short curated set of ordinary words — "camera", "dithering",
  "display mode" — is in there for the reader who does not yet know what the
  program calls the thing. Section titles are deliberately not entries: a
  topic belongs to the contents page, and nobody looks up "Saving What a Run
  Changed".
• Each appendix section opens with a worked TOML fragment. A table of
  settings says what each one means and nothing about where the line is
  written, which left a reader who had found the right knob holding a name and
  no file. Every configuration section, scene type, overlay, generator, effect
  and live-tune mapping now shows the two or three lines that put it in a file,
  with a key's choices as a trailing comment. The fragments are generated from
  the same model as the tables under them and carry only real defaults — a key
  with no default is named in a comment rather than given an invented value.
• The appendices are in alphabetical order. Configuration sections and scene
  types were in declaration order, which reads well in the annotated example
  file and is no use in a book nobody reads in order — finding [wled] meant
  paging through nineteen sections in an order you could not predict. Overlays
  were already sorted.
• A field's type and default say which is which. The two lines under a name
  in every appendix table were bare — str over 'serial' — and only obvious
  to somebody who already knew. They are now labeled Type: and Default:.
• The PDF navigates in the numbers it prints. Page labels — what a reader's
  thumbnail strip and page-number box show — were lowercase roman from the cover
  to the index, on a book whose body is numbered in arabic, so "page 84" and
  page 84 were different pages. The switch at the start of the body now reaches
  the whole document, and a chapter opener is labeled instead of leaving a gap
  in the strip. Both books.
• Reference tables read better. No table cell justifies any more: Appendix
  F's "Declared by" lists fourteen generator names down a 1.6in column, and
  justified they came out as two words a line with a river through them. Ranges
  and value counts are set as literals rather than in the body face, where their
  digits stood taller than the mono names beside them and read as the largest
  thing in the table. Appendix E no longer repeats source. and effect. on
  every one of fifty lines — the holder is stated once above each table — and
  index entries are no longer emboldened, which was setting one column in two
  faces at two apparent sizes.
• Four more tables say a repeated name once. Appendix D's rule table gave
  every refused overlay a row, and ten of the thirteen rows read "needs a
  text-capable mode (petscii/blank/hires/mhires)" — the same sentence read ten
  times to learn one thing. It is by the rule now, four rows for the three
  rules, and the appendix fits the page its matrix is on. Appendix B printed
  duration_s's sixty-word description under nine of its ten scene types; it
  sits with the keys every scene takes, over a line naming video as the
  exception. Appendix F and the Performance Card drop the holder from every
  live-target row the way Appendix E did — Appendix F heads each section with
  the holder itself (mode, effect, source, scene) and says what it
  holds, the card puts it in the column heading.
• The books, and the code, are spelled in American English. colour,
  behaviour, quantise, analyser, centre, catalogue, licence and the
  rest. The program has always named itself in American English — color_match,
  grayscale, palette_mode — so the prose was disagreeing with the keys it
  was telling the reader to type, sometimes in the same sentence. The grey /
  gray color alias is untouched: both still resolve.
• The books no longer talk about their own build. "Generated from the code by
  scripts/gen_reference_appendices.py. Edits here are overwritten" opened every
  appendix and the index; the glossary explained that it was hand-written
  "because a machine has no opinion about which words a reader will not know".
  None of that is for the reader. What the appendices are is still said once,
  in the introduction and the colophon, where it belongs.
• No listing wraps. Typst wraps an over-long line in a code block rather
  than complaining, and a wrapped listing does not look broken — it looks like a
  line the program never printed. --profile's sample came out as six lines of
  four and a class definition wrapped mid-signature. Every listing in all three
  books now fits its measure, and a test holds them to it.
• The Programmer's Reference Guide is illustrated. Five diagrams, for the
  five things in it that are spatial and were being carried entirely by prose:
  the precedence ladder with the extra rung an ensemble inserts, the twelve-step
  display pipeline with the setting that enters at each step, one hardware cell
  in each of the four picture modes with the bytes that color it, the DAC path
  against the sampler path with what each costs the 6510, and the 64 KB during a
  bitmap scene — the VIC's banks drawn as what they are, four 16 KB windows on
  one memory, with color RAM outside all of them. They are drawn by
  scripts/make_reference_diagrams.py in the books' own faces and palette, and
  committed; make reference-figures redraws them.
• The books' symbols no longer depend on the machine that built them. Jost
  has no ✓ and no →, and Typst was filling them from whatever was installed — so
  the compatibility matrix was set in a heavy upright check locally and a thin
  slanted one in CI, from the same source file. Both marks are now drawn by the
  template, Typst's own fallback is off, and a new test fails on any character
  the two vendored faces cannot draw. (One had already got through: a ⇒ in a
  generator's docstring, which is in neither face and was printing as a gap.)
• Inline code in the books is set at 1.08em rather than 1em. The two faces agree
  on x-height but Inconsolata's ascenders and capitals run 12–17% short of
  Jost's, which is what the eye compares when the two meet inside a line, so
  every [section], --flag and 6581 sat visibly low in its sentence.
• The appendices' opener pages no longer print the backticks around a section
  name — the section list was being quoted as a string rather than converted —
  and Appendix B's scene types are headed by the type's name rather than by
  type = "webcam" repeated ten times.
• The Performance Card's pad-light table had its columns labeled backwards.
  Pad | State sat over rows reading Bright | Playing, which is a light and
  what it means, not a pad and its state — and the reverse of the same table in
  the reference guide. It is now Light | Means. The card's gesture table also
  lost pinch-to-resume when its "paused" column was replaced by the performance
  column; the row carries it again.
• The reference guide's keyboard table lists SPACE, which the card
  already had, so the two are the same table. Key names are keycap chips in all
  three books instead of chips in two of them and bold text in the third, and
  they are uppercase throughout, as the keys are.
• The reference guide's glossary defines C64U, TeensyROM+ and Extra,
  and its introduction stops promising that the book carries no reasoning: it
  prints the measurement behind a default where there is one, and leaves which
  other approaches were tried to docs/architecture.md. One passage that was
  pure history with no decision attached is gone.
• The reference guide warns where it should: a launcher scene hands the machine
  away and can stop answering the modifier keys, and --calibrate-dac replaces
  an existing table with no prompt and no backup.
• Appendices G and H are reachable from the prose — the flag list from the
  notation section, the example index from the section on example: names.
  Nothing referred to either of them before.
• The fireworks generator's description no longer carries an internal note
  reference, which was published verbatim in Appendix E and in the release PDF.
• The reference guide can get you connected. Chapter 1 gains "Naming the
  Hardware": every connection-target scheme, what a target decomposes into in
  [hardware], [ultimate64] and [teensyrom], the dma_port / tcp_port /
  baud / storage query parameters, what -s NTSC / -s PAL actually
  changes and why it belongs in machine settings, and a table of the three C64U
  network services against what stops working without each. The one string that
  picks both the backend and its endpoint had appeared only inside two example
  commands, and the volume you open when a machine will not answer never said
  which switch to throw.
• Quick playback's extension-to-scene mapping is in the reference guide's prose
  rather than only inside a help string: which argument becomes which scene,
  what a directory or a glob does, and how a URL's timestamp becomes start_s.
• [interstitial] is documented (Chapter 2) — what the card is, the styles
  it takes, the three things that bypass it, and what else happens at a scene
  boundary.
• Every scene type in the reference guide's catalog now opens with the same
  three facts: which extra it needs, where it looks for files when file is
  omitted, and which display modes it accepts.
• The live-tune write-back is documented (Chapter 6): what --overwrite
  does, what is offered back at exit and what is not, and a warning that saving
  rewrites the whole configuration file from the settings in memory and keeps
  one .bak deep.
• The reference guide's two vaguest chapter titles now say what is in them.
  "Inside the Machine" is The Link and the Memory Map, and "Everything
  Outside" is Inputs and Outputs — which is what a reader scanning the
  contents for MIDI, WLED or recording can actually find. The chapter numbers
  are unchanged, so every cross-reference still lands where it did.
• Extending c64cast is its own chapter (7) rather than the tail of the
  memory-map chapter. Writing a scene, an overlay, a generator or an effect is
  contributor material, and it was sitting inside a user-facing chapter after a
  write budget. It is appended rather than inserted, so chapters 1 to 6 keep
  their numbers.
• ASID and the MIDI scene are no longer written out twice. Chapter 2's
  catalog entries state what a configuration needs — the keys, the extra,
  the ports — and defer the mechanism to Chapter 4, which is the rule the
  introduction sets and was the one place the book broke it.
• Every optional extra is listed in one place, as the reference guide's new
  Appendix I: what each one unlocks, the module --doctor looks for, and the
  packages it installs — with the reason the install to ask for is
  c64cast[all] rather than one extra at a time. The chapters have always named
  an extra where a feature needs one; nothing collected them. The glossary moves
  to Appendix J.
• The books keep the promise their notation section makes. A setting that
  can move while a show is running now says so where it is defined: Appendices A
  and B mark a field live-tunable and name the target a knob reaches it by
  ([color].dither is mode.dither_method, which is exactly the pairing a
  reader could not guess), and mark it menu-live when the on-C64 menu carries
  it as a knob. Appendix E writes each generator's and effect's parameters the
  way a cc_map has to spell them — source.speed, not speed — so a line can
  be copied straight into a mapping.
• The performance card's live-target list says who declares each target. A
  knob mapped to source.ring_freq does nothing unless moire2 is the
  generator on screen, and the column that says so was the one the card dropped
  for space. It is back, and it names them: the modes, effects and generators
  that declare a target, spelled out, because the question at the console is
  whether the thing on screen is in that list and a count — 14 generators —
  cannot answer it. A target nearly everything declares is written as its
  exceptions instead (all but fire, mandelbrot, …). Still two pages.

Fixed

• The reference guide offered https:// as a way to reach a C64U. The
  machine's REST service is plain HTTP on the ordinary port and has no access
  control of its own, so a reader who followed the table got a connection
  failure. The connection-target tables now show http:// only, and the prose
  says what the link actually is and points at SECURITY.md.
• --doctor never reported the wled extra, so a missing zeroconf — the one
  thing standing between [wled].listen and a WLED app that can discover the
  virtual device — showed up as silence in the one command whose job is to say
  what is missing. All twelve extras are now probed, and a test holds the list
  to the extras the package actually declares.