Tape API

Get the global tape instance

Returns — Pointer to tape (never NULL after system init)

Get current tape state

Returns — Current state (TAPE_STATE_UNMOUNTED, TAPE_STATE_IDLE, etc.)

Get tape length in tape positions (SD sectors)

Returns — Tape length in positions. 1 position = 1 sector = 64 stereo frames, so multiply by 64 to compare against tape_read()/tape_write() frames.

Begin recording session

No undo is captured for the take, and the tape's previous undo/redo is dropped. Marks are created on commit.

Returns — Recording handle. A take still open is aborted first.

Note — This only brackets the take (timeline, mark). It writes NO audio - the tapp's engine callback has replaced the one that normally does. Stream the tapp's output to the tape with tape_write() between begin and commit.

Commit recording session

Creates marks for recorded region, commits undo state.

Returns — Final end position

Abort recording (discard without creating marks)

Check if undo is available for last recording

Returns — true if undo data is valid

Execute undo - restore original audio from last recording

Returns — true on success

Number of recording marks on the tape

Returns — Mark count (0 if none / no tape)

Get the start/end of mark `idx`

Returns — true if idx is valid and outputs were written

Read recorded audio into a RAM buffer (stereo-interleaved L,R,...)

Returns — Number of stereo frames actually read

Warning — Blocks on SD DMA. Call from tick()/init() (main thread), NEVER from the audio process() callback. The tapp sequences the slices itself in process().

Write audio to the tape (stereo-interleaved L,R,...)

Clamped to the tape length and addressed from the tape's own data area, so it cannot reach any other file. Partial sectors are read-modify-written.

This is how a TAPP records: ring the process() output in RAM and drain it here from tick(), bracketed by tape_rec_begin()/tape_rec_commit() so a mark is created. Undo covers only what tape_rec_begin() armed - writes outside a begin/commit pair overwrite tape audio permanently.

While a recording, frames written also drive the timeline widget's live-record waveform automatically (anchored at the position passed to tape_rec_begin(); writes below that anchor are not drawn).

Returns — Number of stereo frames actually written

Warning — Blocks on SD DMA. Call from tick()/init() (main thread), NEVER from the audio process() callback.

Claim a pair of DMA windows from the tape's pool

Returns — NULL when the pool is exhausted - ALWAYS check, and fail init() if so

Release the windows back to the pool. Call from deinit().

Request the window needed NEXT, and swap the other one in to play now

This is a two-slot pipeline, and the naming hides it. On a miss the DMA is started into the slot that was current, and the OTHER slot - the one a previous call already filled - becomes what tape_buffer_get_ptr() returns. So the caller does not request the window it is about to play; it requests the one AFTER it, and reads back the one it requested last time. On a hit (either slot already holds pos) nothing is issued and that slot simply becomes current.

Practically: at each window boundary call tape_buffer_update() with pos + TAPE_WINDOW_POS, and play tape_buffer_get_ptr(). After a seek the pipeline is empty, so prime it with TWO calls - the first has nothing valid to hand back, which is why tape_buffer_clear_all_buffers() zeroes both slots: the result is a moment of silence rather than whatever was resident.

Safe from process(): a hit does no I/O, a miss posts one command and returns.

Returns — false only if the SD queue was full - and the slot is relabelled anyway, so it will replay stale audio: treat false as a dropped window, not a retry

The resident window: TAPE_WINDOW_FR stereo frames, interleaved L,R

Read it, and overdub it in place while recording. Valid until the next tape_buffer_update() evicts it.

The other window of the pair - the one being prefetched into.

Write both resident windows back to tape

Recording persists only through eviction, so at the end of a take the resident window(s) still hold audio that nothing has written. Call this once when the take ends, or up to two windows of it are lost.

Drop both windows and force a re-read - after a seek that changes content.

Zero the resident window from `sample_offset` (in floats) to its end

Note — What the decks use to keep the button click out of the tail of a take.

Add a cue (a navigable point of interest) spanning [start, end) frames

Cues are what the device's skip-to-cue navigation steps through. Duplicates within one sector are merged, the list is kept in tape order, and the save is flagged automatically. A cue at position 0 is legal.

Returns — false if the span is empty, shorter than one 64-frame sector, ends past the end of the tape, or the tape already holds 255 cues

Number of cues on the tape

Read cue `idx` (0..tape_cues_count-1), in stereo frames

Cues are stored in tape order, so stepping between them is index +/- 1.

Returns — false if idx is out of range

Erase [start_frame, end_frame): audio, marks, and cues

The audio blocks are zeroed (asynchronously, on the storage task), the span is punched out of the recorded-region marks (a longer mark is split around it), every cue overlapping the span is deleted, and the timeline waveform is refreshed. Everything persists automatically.

Cue indices shift on deletion - re-read tape_cues_count() and re-select afterwards. The erase is captured by the single-level record undo (tape_rec_undo_execute() restores it) for spans up to ~136 s and until the next tape_rec_begin(); longer spans erase without undo. Refused while a recording in progress - commit or abort first.

Returns — false if the span is empty, off-tape, or a take is open