SCRYMAMEReferenceCapturesaudio_recordAlso in DOSBox-X

MAMECaptures

audio_record

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

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

Try it

On Gridlee, a free ROM from mamedev.org, stopped on the card that announces a level. The free set lacks Gridlee's sound samples, so the game is silent here.
Ask

Record the sound of the next 30 frames to a file named card.wav.

Call
audio_record(frames=30, dest="./tmp/demos/tour/card.wav", seconds=300)
Reply 8 of 35 fields
{
  "summary": "audio_record: 24000 samples at 48000 Hz x 1, silent at ./tmp/demos/tour/card.wav",
  "verdict": "ELAPSED",
  "channels": 1,
  "sample_rate_hz": 48000,
  "samples": 24000,
  "emulated_s": 0.50688,
  "sample_min": 0,
  "sample_max": 0
}

The file holds 24000 samples for about half an emulated second. sample_min and sample_max are both 0: the recording is silent, because Gridlee's sound samples are not in the free set.

The whole reply
JSON
{
  "summary": "audio_record: 24000 samples at 48000 Hz x 1, silent at ./tmp/demos/tour/card.wav",
  "status": "ok",
  "verdict": "ELAPSED",
  "frame_before": 594,
  "frame_after": 628,
  "emulated_before_s": 10.053138,
  "emulated_after_s": 10.627602,
  "cycles": 718080,
  "polls": 34,
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "path": "./tmp/demos/tour/card.wav",
  "frames": 30,
  "began": true,
  "frame_begin": 595,
  "recording_after": true,
  "ended": true,
  "bytes": 48044,
  "channels": 1,
  "sample_rate_hz": 48000,
  "samples": 24000,
  "emulated_s": 0.50688,
  "sample_min": 0,
  "sample_max": 0,
  "frame_end": 624,
  "cause": "the `gvblank` stop of the last frame asked",
  "stop_seq": 58,
  "pc": "0x0000fd80",
  "cpu": ":maincpu",
  "frame": 628,
  "regs": {
    "A": "0x00",
    "B": "0xda",
    "D": "0x00da",
    "X": "0x0014",
    "Y": "0xf2e6",
    "U": "0x4071",
    "PC": "0xfd80",
    "S": "0x07f4",
    "CC": "0xd4",
    "DP": "0x00"
  },
  "instruction": {"address": "FD80", "bytes": "0CB2", "text": "INC    <$B2", "symbol": "irq", "delta": 0},
  "following": ["FD82: 96 B2    LDA    <$B2", "FD84: 84 03    ANDA   #$03", "FD86: 26 04    BNE    $FD8C", "FD88: 0C B3    INC    <$B3", "FD8A: 0C B4    INC    <$B4", "FD8C: B6 03 BE LDA    $03BE", "... 9 more"],
  "errorlog": "<volatile>"
}

Arguments

frames integer, required
How many emulated frames of sound to record: 2 or more.
dest string, default ""
An absolute path that does not exist yet. Left empty, the file goes to the session's temporary folder, deleted at close.
seconds number (> 0, <= 600.0), default 60.0
The time limit of the whole call, in seconds of your clock. Left out, 60.

What comes back

path
The WAV, once it has been checked.
samples
How many samples the file holds, at sample_rate_hz a second, for each of its channels.
emulated_s
The emulated time the recording spans, in seconds.
sample_min
The lowest sample value in the file, beside sample_max. The two equal mean a constant level: silence.
ended
true once the recording is closed. false when a stop cut the run short: it stays open until the machine reaches frame_end_planned.
verdict
How the run ended, as run_for reports it: ELAPSED when every frame ran, TIMEOUT when seconds ran out first.
All 44 reply fields
  • console_reruns (integer)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer)
  • pc (string)
  • regs (object)
  • resent (integer)
  • stop_seq (integer)
  • thread_errors (integer)
  • watches (array)
  • emulated_after_s (number or object)
  • emulated_before_s (number or object)
  • ended (boolean)
  • frame_after (integer)
  • frame_before (integer)
  • frame_begin (integer or object)
  • frame_begin_planned (integer)
  • frame_end (integer)
  • frame_end_planned (integer)
  • frames (integer)
  • instructions_completed (integer)
  • lines_ahead (integer)
  • mode (string)
  • path (string)
  • pending (boolean)
  • polls (integer)
  • reader_steps (integer)
  • recording_after (boolean or object)
  • regpoint_hit (object)
  • began (boolean)
  • bytes (integer or object)
  • channels (integer or object)
  • cycles (integer)
  • drain_steps (integer)
  • emulated_s (number or object)
  • sample_max (integer or object)
  • sample_min (integer or object)
  • sample_rate_hz (integer or object)
  • samples (integer or object)
  • tagged_lines (array)
  • verdict (string)
  • watch_hit (object)

What it refuses

Why it works this way

The recording spans exactly frames frame periods of emulated time. MAME's mixer writes in updates of a fiftieth of an emulated second. So the sound begins up to one update before the first frame and ends up to one before the last.

The file is checked before its path is given, because MAME's writer checks none of its writes and fills the header's two sizes only at close. The header must agree with the file, and the samples with the stretch, within one update.

Silence is reported, never refused: it is a fact about the program. A constant level is silence to the ear whether it is zero or not.

More on why

Two is the fewest frames that always hold a mixer update on a screen under 100 Hz.

A stop that cuts the run short leaves the recording open or not begun, as record explains. An open recording gains nothing while the machine stands at the debugger, since no mixer update runs there.

Its marks in error.log, its planned frames and its refusals after the run began follow record's rules.

The contract your client receives
Text
Record the mixer's output for exactly `frames` frames to a WAV, then stop.
Needs the machine STOPPED (else `not_stopped`).

`dest`: an absolute path not there yet; empty lands in the scratch. `frames` is 2 or more.
`seconds` bounds the wait for the recording to end.
The WAV is checked before its path is given; a span with no mixer update, no speaker, or a
mixer already recording is INVALID. Silence is reported, never refused.

Reply, once answered: `verdict`, `path`, `began`, `ended`, `bytes`, `channels`,
`sample_rate_hz`, `samples`, `emulated_s`, `sample_min`, `sample_max`, `note`, the stop
survey. Without an answer, `pending`.

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