199 lines
10 KiB
C
199 lines
10 KiB
C
#ifndef XTC_AUDIO_H
|
|
#define XTC_AUDIO_H
|
|
|
|
#include "xtc_project.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
typedef struct xtc_audio_plan xtc_audio_plan;
|
|
typedef struct xtc_export xtc_export;
|
|
/* Control thread only: bounded 256-frame incremental stereo float32 WAV export.
|
|
* tail_ms 0..60000, rate 8000..192000. Destination must be absolute and absent.
|
|
* No destination is published on error/cancel; destroy cancels/removes temporary.
|
|
* Snapshot preparation may execute trusted plugins. Missing media rejects export. */
|
|
xtc_result xtc_project_render_length(const xtc_project *project,unsigned int rate,unsigned int tail_ms,uint64_t *out_frames);
|
|
xtc_result xtc_export_create(const xtc_project *project,const char *path,unsigned int rate,unsigned int tail_ms,xtc_export **out);
|
|
xtc_result xtc_export_step(xtc_export *job,int *done);
|
|
xtc_result xtc_export_progress(const xtc_export *job,uint64_t *position,uint64_t *total);
|
|
void xtc_export_destroy(xtc_export *job);
|
|
typedef struct xtc_recorder xtc_recorder;
|
|
|
|
/* Control-thread metadata edits; audio/silent clips only. No source-file writes.
|
|
* Gain 0..4, fade durations 0..source_length_tick, measured at current tempo.
|
|
* Fades follow audible trimmed boundaries; 0 disables the explicit fade. */
|
|
xtc_result xtc_project_set_clip_audio(xtc_project *project, uint64_t clip, float gain,
|
|
uint64_t fade_in_tick, uint64_t fade_out_tick);
|
|
/* Split strictly inside the timeline range. Left keeps ID; right receives a
|
|
* fresh ID and adjusted source offset. Gain/source/name retained. Inner explicit
|
|
* fades cleared; outer fades retained. Transactional; output unchanged on error. */
|
|
xtc_result xtc_project_split_audio(xtc_project *project, uint64_t clip, uint64_t tick, uint64_t *out_right);
|
|
|
|
/* Immutable waveform summary, created/destroyed on control thread only. Uses
|
|
* the same bounded WAV reader/downmix as playback; no media writes. Up to 1024
|
|
* equal frame bins, fewer for short media. Peaks are raw source, before gain or
|
|
* fades. Accessors read cached memory only. Load errors are explicit. */
|
|
typedef struct xtc_waveform xtc_waveform;
|
|
xtc_result xtc_waveform_create(const char *path, xtc_waveform **out);
|
|
void xtc_waveform_destroy(xtc_waveform *waveform);
|
|
xtc_result xtc_waveform_info(const xtc_waveform *waveform, unsigned int *rate, size_t *frames, size_t *bins);
|
|
xtc_result xtc_waveform_peak(const xtc_waveform *waveform, size_t bin, float *minimum, float *maximum);
|
|
|
|
/* Control-thread sample-peak normalization of audible native-rate source slices
|
|
* (same mono downmix as playback). target 0<peak<=1, replaces clip gain, ignores
|
|
* fades/track mix. Gain >4, silence, missing/invalid media or MIDI reject the
|
|
* entire unique nonempty selection. Reads media; no source writes. */
|
|
xtc_result xtc_project_normalize_audio(xtc_project *project,const uint64_t *ids,size_t count,float target);
|
|
/* Control-thread WAV import: PCM16/24/32 or float32, mono/stereo downmixed to
|
|
* mono, 1..768000 Hz. Absolute canonical references, <=511 bytes.
|
|
* Adds a timeline source -> output route if no timeline source exists.
|
|
* Transactional; track must exist. Duration rounds up to a musical tick. */
|
|
/**
|
|
* @brief Imports a WAV reference as a clip and ensures a timeline output route exists.
|
|
*
|
|
* @param project Project model; borrowed for this call.
|
|
* @param track Stable track identifier.
|
|
* @param path NUL-terminated file or asset path.
|
|
* @param start_tick Start position in musical ticks.
|
|
* @param out_clip Receives the clip.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_project_import_audio(xtc_project *project, uint64_t track, const char *path, uint64_t start_tick,
|
|
uint64_t *out_clip);
|
|
/* Empty path makes a region silent; nonempty path must be absolute. Does not
|
|
* open the file. Missing references survive save/load for later relinking. */
|
|
/**
|
|
* @brief Sets an absolute audio asset reference, or clears it to make a region silent.
|
|
*
|
|
* @param project Project model; borrowed for this call.
|
|
* @param clip Stable clip identifier.
|
|
* @param path NUL-terminated file or asset path.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_project_set_clip_asset(xtc_project *project, uint64_t clip, const char *path);
|
|
/* Immutable/preloaded plan. At most 64 distinct assets, 16M mono frames/asset,
|
|
* 64M total frames, 256 MiB file and 4096 chunk input limits. Missing/invalid assets become silence with explicit
|
|
* issues. OOM/capacity fails creation. No file access during render. */
|
|
/**
|
|
* @brief Preloads audio assets and compiles an immutable arrangement snapshot for rendering.
|
|
*
|
|
* @param project Project model; borrowed for this call.
|
|
* @param rate Sample rate in hertz.
|
|
* @param out_plan Receives the newly allocated plan; caller owns it on success.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_audio_plan_create(const xtc_project *project, unsigned int rate, xtc_audio_plan **out_plan);
|
|
/**
|
|
* @brief Releases preloaded samples and arrangement state; accepts NULL.
|
|
*
|
|
* @param plan Preloaded arrangement plan.
|
|
*/
|
|
void xtc_audio_plan_destroy(xtc_audio_plan *plan);
|
|
/* Control thread before publication only. Zero (default) preserves raw samples;
|
|
* 1..65536 applies linear fades to each audible region's actual media bounds.
|
|
* Rendering remains stateless, including seeks and variable block partitions. */
|
|
xtc_result xtc_audio_plan_set_fade_frames(xtc_audio_plan *plan, size_t frames);
|
|
/**
|
|
* @brief Returns the number of asset issues and optionally the first affected path.
|
|
*
|
|
* @param plan Preloaded arrangement plan.
|
|
* @param out_first_path Receives the first path.
|
|
* @return Number of unique asset issues; zero for a NULL plan.
|
|
*/
|
|
size_t xtc_audio_plan_issues(const xtc_audio_plan *plan, const char **out_first_path);
|
|
/* Single consumer; output replaced with overlap-summed mono, clip/track gain and fades.
|
|
* Linear rate conversion, no time stretching. Output must have frames floats. */
|
|
/* Stereo outputs must be distinct; NULL right selects mono gain-only rendering. */
|
|
/**
|
|
* @brief Replaces output with the overlap-summed timeline mix, applying clip gain/fades and track gain/pan.
|
|
*
|
|
* @param plan Preloaded arrangement plan.
|
|
* @param position Absolute sample position at the start of the block.
|
|
* @param left Destination left-channel buffer.
|
|
* @param right Destination right-channel buffer; NULL selects mono rendering.
|
|
* @param frames Number of audio frames.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_audio_plan_render_stereo(const xtc_audio_plan * plan, uint64_t position, float *left, float *right, size_t frames);
|
|
/**
|
|
* @brief Renders the timeline to a mono output buffer using track gain without pan.
|
|
*
|
|
* @param plan Preloaded arrangement plan.
|
|
* @param position Absolute sample position at the start of the block.
|
|
* @param output Destination buffer with room for the requested frames.
|
|
* @param frames Number of audio frames.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_audio_plan_render(const xtc_audio_plan *plan, uint64_t position, float *output, size_t frames);
|
|
/* Control-thread creation opens a same-directory temporary float32 WAV.
|
|
* Ring capacity 1..2097152 frames. One callback producer, one control consumer.
|
|
* push accepts whole blocks; overflow is sticky and all later input is dropped.
|
|
* drain performs file I/O; call regularly. finish requires producer quiescence,
|
|
* drains, finalizes and publishes without overwriting even on overflow (partial recovery).
|
|
* No source/recorder is freed until destroy, which also removes unfinished temp.
|
|
* Counts and sticky error can be observed while producing. */
|
|
/**
|
|
* @brief Allocates a bounded recording ring and opens a temporary mono float32 WAV file.
|
|
*
|
|
* @param path NUL-terminated file or asset path.
|
|
* @param rate Sample rate in hertz.
|
|
* @param capacity Recording ring capacity in frames, from 1 to 2097152.
|
|
* @param out_recorder Receives the newly allocated recorder; caller owns it on success.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_recorder_create(const char *path, unsigned int rate, size_t capacity, xtc_recorder **out_recorder);
|
|
/**
|
|
* @brief Enqueues an entire audio block without blocking; overflow sets a sticky error.
|
|
*
|
|
* @param recorder Recorder handle.
|
|
* @param input Borrowed input sample buffer.
|
|
* @param frames Number of audio frames.
|
|
*/
|
|
void xtc_recorder_push(xtc_recorder *recorder, const float *input, size_t frames);
|
|
/**
|
|
* @brief Writes queued samples to the temporary WAV file on the control thread.
|
|
*
|
|
* @param recorder Recorder handle.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_recorder_drain(xtc_recorder *recorder);
|
|
/**
|
|
* @brief Drains and finalizes the WAV file, then renames it after producer quiescence.
|
|
*
|
|
* @param recorder Recorder handle.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_recorder_finish(xtc_recorder *recorder);
|
|
/**
|
|
* @brief Copies the number of accepted frames and returns the sticky recording status.
|
|
*
|
|
* @param recorder Recorder handle.
|
|
* @param out_frames Receives the frames.
|
|
* @return XTC_OK on success, or an error code describing the failure.
|
|
*/
|
|
xtc_result xtc_recorder_status(const xtc_recorder *recorder, uint64_t *out_frames);
|
|
/**
|
|
* @brief Finalizes pending accepted frames after producer quiescence; preserves failed temporaries.
|
|
*
|
|
* @param recorder Recorder handle.
|
|
*/
|
|
void xtc_recorder_destroy(xtc_recorder *recorder);
|
|
/* Default create refuses any existing destination (including symlinks). Explicit
|
|
* replacement retains the old behavior for callers that obtained authorization.
|
|
* Final publication is race-safe: no-clobber link, or explicit replace/rename. */
|
|
xtc_result xtc_recorder_create_replace(const char *path, unsigned int rate, size_t capacity, int replace,
|
|
xtc_recorder **out_recorder);
|
|
/* Control-thread borrowed path. After a failed finish, copy before destroy.
|
|
* Useful temporary data survives destroy on failed finalization. */
|
|
const char *xtc_recorder_recovery_path(const xtc_recorder *recorder);
|
|
/* Salvage complete mono float32 frames from xtc's interrupted recording format
|
|
* to a NEW destination. Never modifies the source or overwrites an existing file. */
|
|
xtc_result xtc_recorder_recover(const char *temporary, const char *destination);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|