SCRYMAMEReferenceCapturesaudio_recordAlso in DOSBox-X
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
Record the sound of the next 30 frames to a file named card.wav.
audio_record(frames=30, dest="./tmp/demos/tour/card.wav", seconds=300){
"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
{
"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_hza second, for each of itschannels. - 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
trueonce the recording is closed.falsewhen a stop cut the run short: it stays open until the machine reachesframe_end_planned.- verdict
- How the run ended, as
run_forreports it:ELAPSEDwhen every frame ran,TIMEOUTwhensecondsran 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
framesunder 2, or adestthat exists (bad_argument).- A machine that is running (
not_stopped). - A machine with no screen or no frame counter (
no_channel). - A stretch with no mixer update, a machine with no speaker, or a mixer already recording (
readback_refused). - A WAV whose header, length or sample count does not agree with the run (
readback_refused). - A script that answered and logged no mark, not even the line it writes as it is evaluated (
readback_refused). - A script MAME's console ran twice (
console_rerun).
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.
Related tools
The contract your client receives
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.