SCRYDOSBox-XReferenceCapturesaudio_recordAlso in MAME

DOSBox-XCaptures

audio_record

Record an exact number of frames of sound to a WAV, a DRO or a MIDI file, then stop the program again.

audio_record(frames, dest="", seconds=60.0, kind="wav")

Try it

On Minesweeper, a game this repository builds, stopped a few frames after a click on a mine, with the explosion already sounding.
Ask

Record the sound of the next 45 frames to a file named boom.wav.

Call
audio_record(frames=45, dest="./tmp/demos/mines/boom.wav")
Reply 9 of 30 fields
{
  "summary": "audio_record wav 45 frames: ELAPSED, 30768 samples at 48000  ... (92 characters)",
  "verdict": "ELAPSED",
  "kind": "wav",
  "channels": 2,
  "sample_rate_hz": 48000,
  "samples": 30768,
  "emulated_s": 0.6413212,
  "sample_min": -18099,
  "sample_max": 18479
}

A stereo WAV of 30768 samples, about 0.64 emulated seconds. sample_min and sample_max are far apart, so the recording is not silent.

The whole reply
JSON
{
  "summary": "audio_record wav 45 frames: ELAPSED, 30768 samples at 48000 Hz at ./tmp/demos/mines/boom.wav",
  "status": "ok",
  "verdict": "ELAPSED",
  "polls": 45,
  "pc": "08DF:00000E08",
  "cpu_mode": "real",
  "frame": 945,
  "regs": {
    "EAX": "0x00000004",
    "EBX": "0x00000000",
    "ECX": "0x00000160",
    "EDX": "0x000003da",
    "ESI": "0x000017d5",
    "EDI": "0x00000fe3",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffc",
    "EIP": "0x00000e08",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0x08df",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [],
  "cause": "no declared code breakpoint at 08DF:00000E08, and the debugger does not say which row stopped the machine, so what made this stop cannot be told",
  "e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
  "stop_seq": 668,
  "instruction": {
    "address": "08DF:00000E08",
    "bytes": "A808",
    "text": "test al, 8",
    "flow": "sequential",
    "code_bits": 16,
    "bytes_from": "memory",
    "symbol": "retrace",
    "delta": 9
  },
  "emulated_before_s": 12.818086224999998,
  "emulated_after_s": 13.459407425,
  "frame_before": 900,
  "frame_after": 945,
  "cycles": 1789674,
  "kind": "wav",
  "frames": 45,
  "began": true,
  "ended": true,
  "path": "<volatile>",
  "bytes": 123116,
  "channels": 2,
  "sample_rate_hz": 48000,
  "samples": 30768,
  "emulated_s": 0.6413212,
  "sample_min": -18099,
  "sample_max": 18479
}

The three kinds

kind what is recorded
wav The mixer's output: everything the machine plays, as samples.
dro The writes to the OPL chip's registers, as a DRO 2.0 file.
mid The MIDI bytes the program sends, as a MIDI file.

Arguments

frames integer, required
How many frames of the emulated display the recording lasts: 1 or more.
dest string, default ""
A path that does not exist yet, absolute or starting with ~. Left empty, the file stays where the emulator wrote it.
seconds number (> 0, <= 600.0), default 60.0
The time limit of the whole call, in seconds of your clock. Left out, 60.
kind one of "wav", "dro", "mid", default "wav"
wav, dro or mid, as above. Left out, wav.

What comes back

path
The file, once it has been checked. Unavailable, with the reason, when the run had no OPL note or MIDI byte.
emulated_s
For a WAV: the emulated time the recording spans, in seconds.
sample_min
For a WAV: the lowest sample value, beside sample_max. The two equal mean a constant level: silence.
opl_pairs
For a DRO: how many register writes and delays the file holds; opl_ms is its length in milliseconds.
files
For a DRO, when the OPL writer began a new file during the run: every file, each with its path and bytes.
ended
true once the capture is turned off. false when it could not be: there is no path, and it records until close.
All 35 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • cycles (integer or object)
  • e9 (object)
  • emulated_after_s (number or object)
  • emulated_before_s (number)
  • enrichment (object)
  • frame (integer or object)
  • frame_after (integer or object)
  • frame_before (integer or object)
  • instruction (DosboxInstruction)
  • pc (string or object)
  • polls (integer)
  • regs (object)
  • retrace_pending (boolean)
  • stop_seq (integer)
  • verdict (string)
  • watches (array)
  • began (boolean)
  • bytes (integer)
  • channels (integer)
  • emulated_s (number or object)
  • ended (boolean)
  • files (array of object)
  • frames (integer)
  • kind (string)
  • midi_bytes (integer)
  • opl_ms (integer)
  • opl_pairs (integer)
  • path (string or object)
  • sample_max (integer)
  • sample_min (integer)
  • sample_rate_hz (integer)
  • samples (integer)

What it refuses

Why it works this way

The recording is counted in frames of the emulated display, as record counts them: CAPTURE turns the kind on at this stop and off at the stop the run reaches. The file holds what was emulated in between.

Each file is checked before its path is given. A WAV's header must agree with its file, whose two sizes the emulator fills only at close, and its samples with the run's emulated time. The mixer works in ticks of an emulated millisecond, so one tick at each end is allowed.

Silence is reported, never refused: it is a fact about the program. The OPL writer opens its file at the first note and the MIDI writer at the first byte, so a run with neither has no file.

More on why

A readback_refused that comes and goes is the configuration's clock first. When your computer cannot run the program's fixed cycles in real time, the mixer loses whole blocks and the WAV falls short. Lower the fixed cycles and record again.

  • A DRO must be a DRO 2.0 file whose header's length is the file's: the register state at its first event, then each write.
  • A MIDI file must be a header and a track whose length reaches the end of the file; midi_bytes counts its events' bytes.
  • The OPL writer begins a new file after half a minute of emulated silence. path is then the last file, and the checks and counts are that file's alone.
The contract your client receives
Text
Record exactly `frames` retraces of sound, then stop: the mixer to a WAV (`kind`
`wav`), the OPL register writes to a DRO (`dro`) or the MIDI bytes to a MIDI file
(`mid`). Needs the machine STOPPED and a build whose debugger has `CAPTURE`.

`dest`: an absolute or `~`-led path not there yet; empty leaves the file where the emulator
wrote it. `seconds` bounds the wait for the recording. The file is checked before its path is
given (a rolled-over OPL run: the last); a WAV whose samples miss the run's emulated span by
more than 2 mixer ticks is INVALID. Silence is reported, never refused; a run with no
OPL note or MIDI byte has no file (`path` unavailable). A run cut short is checked for what it
holds; a capture that could not be turned off is `ended: false`, no `path`, and records until
`close`.

Refused: `frames` under 1, that kind already on, a build with no `CAPTURE`, a running
machine.

Reply: `verdict`, `kind`, `frames`, `began`, `ended`, `path` (none if the capture could not be
turned off), `bytes` (a file was written); a WAV's `channels`, `sample_rate_hz`, `samples`,
`emulated_s`, `sample_min`, `sample_max`; a DRO's `opl_pairs`, `opl_ms` (the last file's);
`files` (each `path`, `bytes`) when the OPL writer rolled over to a new file, `path` then the
last; a MIDI file's `midi_bytes`; `note`, the run's fields, the stop: `pc` (`SSSS:OOOOOOOO`), `cpu_mode`, `stop_seq`, `frame`, `instruction`, `regs`, `watches`, `cause`, `regpoint_hit` (a registerpoint stopped it) and `e9`.

Reference: REFERENCE.md, Input and the screen.
Tools