SCRYDOSBox-XReferenceCapturesaudio_recordAlso in MAME
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
Record the sound of the next 45 frames to a file named boom.wav.
audio_record(frames=45, dest="./tmp/demos/mines/boom.wav"){
"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
{
"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,droormid, 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_msis its length in milliseconds. - files
- For a DRO, when the OPL writer began a new file during the run: every file, each with its
pathandbytes. - ended
trueonce the capture is turned off.falsewhen it could not be: there is nopath, and it records untilclose.
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
framesunder 1, or adestthat exists (bad_argument).- A machine that is running (
not_stopped). - That kind of capture already on, or a build whose debugger has no
CAPTUREcommand (no_channel). - A WAV that holds no sample, or whose samples miss the run's emulated time by more than 2 mixer ticks (
readback_refused). - A DRO or a MIDI file whose header disagrees with the file (
readback_refused).
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_bytescounts its events' bytes. - The OPL writer begins a new file after half a minute of emulated silence.
pathis then the last file, and the checks and counts are that file's alone.
Related tools
The contract your client receives
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.