How to Read This Book
The User's Guide teaches c64cast in order, from a first run to a playlist you would show somebody. This book does not teach it. It is the volume you open when you already know what you want and need to know exactly what it is called, what it accepts, and what it does when you say nothing at all.
It is organized by subsystem, not by audience. The musician driving a SID and the VJ driving a club wall read the same chapter on sound, because it is the same sound path. Where a subject belongs to two chapters it is written once and referred to from the other.
What Is In Here#
Chapters 1 to 6 are prose: the rules of the configuration language, the vocabulary of scenes and overlays, the display pipeline from frame to VIC-II register, the sound path, the link into the Commodore's memory and what lands there, and everything that reaches c64cast from outside or leaves it.
Chapter 7 is the exception, and is for a different reader: it is what you need to add a scene, an overlay, a generator or an effect to c64cast itself. Nothing in the first six chapters depends on it.
Appendices A to I are not prose. Each is a complete table of one kind of thing — every configuration field, every scene key, every overlay parameter, every flag — read out of the same definitions the program answers --describe, --compat and --print-schema from. A table in this book cannot disagree with the program it documents. Each opens with a short fragment of a configuration file, because a name and a default still leave the question of where the line is written.
The chapters name an optional install extra wherever a feature needs one — video for a video scene, midi for a MIDI one, wled for the virtual WLED device. Appendix I is the whole list, with what each extra unlocks and what it installs.
Appendix J is a glossary of the terms this book uses without stopping.
The index at the back is every name c64cast answers to, against the pages that discuss it. A configuration 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 would look for it and axis (effect) is what you find. A few entries are ordinary words rather than anything the program prints — "camera", "dithering" — for the reader who does not yet know what it calls the thing.
What Is Not#
Three things live outside this book on purpose.
docs/architecture.md and the notes it indexes are the contributor's account of why each module is built the way it is, including the approaches that were tried and abandoned. Read it before changing a module.
This book does explain itself where a default would otherwise look arbitrary, and it prints the measurement that settled the matter when there is one — a sampler clock rate, a frame budget, how much louder one companding curve is than another. What it leaves to architecture.md is the history: which other approaches were tried, and why they lost.
docs/caveats.md records the hardware's own limits, which are frequently the real answer to "why can't it just". docs/troubleshooting.md is organized by symptom, which is the right index when something is wrong and the wrong one when you are designing.
Notation#
A name in this face is something you type or something the program prints: a configuration key, a command-line flag, a file, a value. A section of a configuration file is written with its brackets, as [audio], and a repeated table with its double brackets, as [[scenes]], exactly as TOML spells them. A key inside a particular section is qualified when there is any doubt: [audio].backend.
Values are shown as TOML writes them, so a string carries its quotes and a number does not. Where a key takes one of a fixed set of values, the set is listed in full; where it takes a free string, the shape of that string is given by example.
Two marks say that a setting can change while a show is running, and they are different powers. A parameter marked live-tunable can be moved by a MIDI knob, a pad or the web console; the mark names the holder.name target string that reaches it, and Appendix F lists every one of them. A key marked menu-live is one the on-C64 menu offers as a knob, applying the change to the running scene; a key without the mark is not in the panel at all, because changing it would mean rebuilding the scene. A setting can carry both: a scene's palette_mode is on a MIDI knob as mode.palette_mode and is in the menu.
A command-line flag is written as it is typed, with its leading dashes, as --config. Flags are introduced beside the behavior they change rather than cataloged in the prose; Appendix G is the full list, in the groups -h prints them in.
Where a Setting Comes From#
Every value c64cast uses is resolved through one ladder, and every layer beats the ones below it. Stated once, formally, for a single system:
- The built-in default, which is the value in the dataclass field.
- Machine settings, from
~/.config/c64cast/settings.toml— the connection target, capture devices and SID model this particular computer should assume when nothing says otherwise. - The configuration file: the one named by
--config, else./c64cast.tomlif it exists. - Command-line flags.
- The environment, which today is only
C64CAST_DMA_PASSWORD, and which is the environment precisely so that a password never reaches shell history or a process listing.
An ensemble run inserts one layer. Each system resolves defaults, then machine settings, then its own configuration file; then the master file's cascade fills in only those fields still sitting at the machine-overlaid baseline, so a per-system file always beats the master that gathered it; then flags and the environment as before.
This ladder is the whole of the rule. Chapter 1 works through what each layer is for and how to see which one supplied a given value.