ByteTerrace/Puck / .claude/skills/media
media
VerifiedMaps Puck sound and recording: Puck.Audio mixer and synth, speakers, cues, music director, voice babble, HUD text speech, audio.render, capture.start clips, Puck.Recording (Opus, AV1, Matroska).
Media
A map of what Puck plays and what it records. Sound and recording share no
code, but both are presentation output that must never feed simulation, and
both reach real hardware only through Puck.Platform seams (platform).
- Sound.
Puck.Audioholds the deterministic mixer and synth (Puck.Audio.Mixing) and the music, babble and clock primitives that are simulation state (Puck.Audio.Simulation). It parses no document.Puck.Worlddrives it:WorldAudioDirectorderives the emitter table from the delivered world,WorldAudioRenderServiceowns the device, and the document intake lives insrc/Puck.World/Audio/. - Recording.
Puck.Recordingis the platform-neutral recording graph: aRecordingDocument, aRecordingSessionthat drives it against encoder and audio-capture factories, a deterministic Matroska/WebM muxer and an Opus lane. Encoders and loopback or microphone capture live inPuck.Platform.Windows; Linux registers factories that decline.
Audio and recording are the human references; the World audio README documents the presentation side. When this file and the code disagree, the code wins and this file is corrected in the same change.
Find the owner by what you need
| You need | Owner | Read |
|---|---|---|
| A sound at a place in the world (a speaker, a machine's audio, a creation's sound) | speakers rows (WorldSpeakerFeed, WorldSpeakerAttenuation) → WorldAudioDirector emitters → AudioSnapshot → AudioMixer | World audio README |
| A one-shot sound on an event (a stinger, an edit echo) | an audio.cues row (WorldAudioCue) naming an event token and a patches row; WorldAudioDirector.SubmitCue | audio reference |
| A synthesized instrument voice | a puck.synthesizer-patch.v1 document, crossed into VoicePatch by WorldVoicePatchFactory.FromDocument, played by VoiceSynth | World audio README |
| Background music that changes with play: segments, layers, embellishments, a beat clock | music rows (WorldMusicRow) compiled by MusicDirectorFactory into MusicDirector and MusicClock; edges from WorldEventFeed become MusicSenseEdges | audio reference |
| A rhythm hit window | a compareState range over the $clock:<music>:phaseError operand; no dedicated grader | audio reference |
| A tune or a playable instrument | tunes rows (WorldTune, puck.tune.v1): TuneMachineSource for a passive tune, TuneInstrumentEngine for an engageable screen machine whose tempo folds into the music clock through WorldServer.InstrumentClockBoundary | World audio README |
| An identity that babbles in syllables | WorldIdentityDefinition.Voice → WorldAudioDirector.TriggerBabble → VoiceBabbler.ComputeTriggerTicks | audio reference |
| A HUD element or sign that reads its text aloud | a HUD Text element's voice (patchId or sampleSet), observed by WorldHudSpeechFeed, played by TextSpeechSource | text speech, samples |
| A WAV of an utterance without a device | audio.render <panelId> <elementId> <output.wav> through WorldSpeechRenderer | text speech |
| Speaker gain bound to state | the shared bindable scalar grammar, resolved through the state mirror each publication | speaker gain |
| The output device, its faults and rebinds | WorldAudioRenderService over IAudioRenderDeviceFactory (Windows: WasapiAudioRenderDeviceFactory) | World audio README |
| A gameplay clip with game audio and microphone | capture.start/status/stop (WorldRecordingCommandModule) or --recording, loading a RecordingDocument and arming a RecordingSession on the host's FrameCaptureController | recording |
| A still frame to PNG from a host | CaptureSink (and ICaptureFrameObserver), an ICaptureSink; a World's own stills are world.screenshot (puck-world console) | frame capture |
| Text, boxes or a timecode burnt into the recording only | OverlayCompositor over the document's overlay rows | frame capture |
| A container, codec or track question | MatroskaMuxer and EbmlWriter; OpusAudioLane, OpusStreamEncoder, LinearResampler; Av1TemporalDelimiterFilter | muxing and codecs |
| A deterministic re-run of a session | replay.* and the replay tape (puck-world), not a recording | replay |
Contracts that bite
- Sound decides nothing. The mixer, synth and emitter table are
presentation: no simulation read depends on them.
MusicClock,MusicDirectorandVoiceBabblerare the exception, simulation state stepped by the server and hashed with it; they never read the wall clock and their seeds fold identity, ordinal and index only. - The document crosses in one place.
Puck.AudioreferencesPuck.Abstractions,Puck.Assets,Puck.Commands,Puck.HostingandPuck.Mathsexactly (the architecture gate's closure). A patch becomes aVoicePatchonly throughWorldVoicePatchFactory. - Plays silent, never crashes. A failed endpoint parks the pump, detaches
the mixer and retries; a host with no backend (Linux, headless) reports
device=unsupportedand machines synthesize at rate zero (MachineAudioRate). - Speech is a function of text and voice.
TextSpeechSourceschedules characters at exact audio-frame boundaries with no wall clock, frame delta or history, so two exports of the same text and voice are byte-identical. - Capture is a product capability (owner ruling). Keep the
capture.*surface,--recording, the document format, the Windows encoder ladder and loopback and microphone capture, and the Linux factories, even with no current world caller (puck-world). Headless Worlds do not compose the capture verbs. - A factory declines with a reason, never throws.
RecordingSession.TryCreateopens only what the machine can encode and capture and fails whole when neither a video encoder nor an audio lane resolves. - Capture never blocks rendering. The render thread copies into a free
FrameSlotQueueslot; a full queue drops the newest frame and counts it. - Choose the clock deliberately.
RecordingClock.Wall(the default) stamps from the wall clock;RecordingClock.Simstamps frames from the tick clock for a deterministic offline re-render and forbids audio rows. - Container bytes are deterministic for the same tracks and blocks;
the live file is crash-safe through a
Voidreservation that a cleanStopreplaces with aSeekHead.
Where each contract is enforced
| Contract | Enforced by |
|---|---|
Puck.Audio's exact dependency closure | puck architecture (build/Architecture.props) |
| One document boundary for patches | WorldVoicePatchFactory.FromDocument, the only converter |
| A malformed recording document is never half-accepted | RecordingDocumentValidator, run by RecordingDocumentSerialization.TryLoad |
| Every Matroska element is written one way | EbmlWriter's typed helpers |
| A crash leaves a playable prefix | the Void reservation in MatroskaMuxer; MatroskaSeekHeadRecoveryLawTests |
| Sim-clock sessions carry no audio | RecordingDocumentValidator, which refuses audio rows under RecordingClock.Sim |
Open gaps
- No Linux backends. No audio render, video encoder or audio capture on Linux; the factories decline by name.
- A babbling identity has no world position. Every syllable, like every embellishment, voices listener-placed.
- Music layer and embellishment
gainThousandthsdo not reach presentation gain (MusicLayerDocument.GainThousandths). - Nothing proves a region crossing's
music.transitioncue end to end. LinearResampleris linear, not polyphase or anti-aliased.- AV1 OBU framing has one home.
Av1Obu.TryRead(Puck.Abstractions) frames a header, extension and size and refuses a set forbidden bit;Av1BitstreamandAv1TemporalDelimiterFilterboth walk through it. - The references' and README's canaries (
voice-babble,music-conditional-layer-and-embellishment,instrument-clock-source) are quarantined underexperimental/.
Verify
- Unit laws:
tests/Puck.Audio.Tests(mixer, synth,MusicClock,MusicDirector,VoiceBabbler),tests/Puck.Recording.Tests. - Headless speech: boot the debug world and run the reference's
audio.renderrecipe (text speech) twice; two exports of unchanged text and voice are byte-identical. The guide and the map sign inworlds/debug/guide.puckare the live examples. - Live sound needs a windowed World with an audio device, which is a GPU leg
(
verification): readaudio.state(device, frames, faults,peak),audio.emitters,speaker.state(includinglastCue:<token>),voice.state,music.stateandinstrument.stateover stdin. - A clip:
capture.start,capture.status,capture.stopon a windowed World, then inspect the file; a lane that declined reports its reason rather than failing the session.
Look-alikes
replay.*records inputs for deterministic re-simulation;capture.*records pixels and sound. Neither substitutes for the other.world.screenshotandworld.captures(scheduled captures in a test) arepuck-worldconsole verbs over the same frame-capture controller.- A machine's own audio (an emulator's APU) belongs to
gaming-bricks; the mixer only binds its output to a speaker. - Camera and desktop capture feeds that a screen shows are
platformcapture services, not recording.
Route adjacent work
| Skill | Route there for |
|---|---|
puck-world | speakers, audio.cues, music, tunes, patches and HUD rows, console verbs, booting and driving a World. |
platform | The WASAPI render device, the Media Foundation encoder ladder, loopback and microphone capture, camera and desktop capture. |
gaming-bricks | An emulated machine's sound hardware and the tune cartridge's core. |
rom-forge | Authoring the puck.tune.v1 jukebox cartridge chain. |
maths-usage | Fixed-point gains, seeded streams and the music clock's arithmetic. |
verification | GPU legs for windowed Worlds, the private CLI copy. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |