xtc/include/xtc/xtc_mixer.h

#ifndef XTC_MIXER_H
#define XTC_MIXER_H

#include "xtc_project.h"

#ifdef __cplusplus
extern "C" {
#endif

#define XTC_MAX_AUTOMATION_POINTS 1024U
#define XTC_HISTORY_EDITS 32U

typedef enum {
    XTC_AUTOMATION_GAIN = 0,
    XTC_AUTOMATION_PAN = 1
} xtc_automation_parameter;

typedef struct {
    uint64_t track_id, tick;
    xtc_automation_parameter parameter;
    float value;
    unsigned int step; /* 0 linear, 1 hold; mode starts at this point. */
} xtc_automation_point;

/* Buses share the 64 track/automation capacities. A bus cannot contain clips
 * or feed another bus. Deleting a bus returns its member tracks to master.
 * Solo is inclusive: a solo bus admits all its members, a solo track admits
 * itself through its bus; bus mute always wins at the bus output. */
xtc_result xtc_project_add_bus(xtc_project *project, const char *name, uint64_t *out_id);
xtc_result xtc_project_route_track(xtc_project *project, uint64_t track, uint64_t bus_or_master);
/* UI/control-thread sample peak display, dBFS floor -90; instant attack,
 * 20 dB/s release, sticky >=1 clip indication. No loudness/true-peak estimate. */
typedef struct { float db; int clipped; } xtc_peak_meter;
void xtc_peak_meter_reset(xtc_peak_meter *meter);
xtc_result xtc_peak_meter_update(xtc_peak_meter *meter, float linear_peak, double seconds);

/* Gain 0..4, pan -1..1, mute/solo 0 or 1. Track audio and scheduled MIDI only.
 * Linear pan: center unity on both outputs; hard pan attenuates opposite side.
 * Automation replaces the corresponding static value, linear/hold per point,
 * holds first/last outside the lane. Duplicate track/parameter/tick replaces. */
/**
 * @brief Sets a track's gain, pan, mute, and solo controls after validation.
 *
 * @param p Project model; borrowed for this call.
 * @param track Stable track identifier.
 * @param gain Linear gain, 0 to 4 for track controls.
 * @param pan Pan position from -1 (left) to 1 (right).
 * @param mute Track mute flag, 0 or 1.
 * @param solo Track solo flag, 0 or 1.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_project_set_mix(xtc_project * p, uint64_t track, float gain, float pan, int mute, int solo);
/**
 * @brief Inserts an automation point, replacing any point at the same track, parameter, and tick.
 *
 * @param p Project model; borrowed for this call.
 * @param a Automation point to read or update.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_project_set_automation(xtc_project * p, const xtc_automation_point * a);
/**
 * @brief Removes the automation point at the specified track, parameter, and tick.
 *
 * @param p Project model; borrowed for this call.
 * @param track Stable track identifier.
 * @param param Automation lane selector.
 * @param tick Musical position in ticks.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_project_remove_automation(xtc_project * p, uint64_t track, xtc_automation_parameter param, uint64_t tick);
/**
 * @brief Copies the number of automation points in the project.
 *
 * @param p Project model; borrowed for this call.
 * @param n Receives the item count.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_project_automation_count(const xtc_project * p, size_t * n);
/**
 * @brief Copies an automation point selected by dense list index.
 *
 * @param p Project model; borrowed for this call.
 * @param i Zero-based index in the dense list.
 * @param a Automation point to read or update.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_project_get_automation(const xtc_project * p, size_t i, xtc_automation_point * a);
/* Control-thread snapshot history; 32 edits plus baseline, no assets/DSP/GUI.
 * record clones before changing history; failure retains all history. checkout
 * clones adjacent state without moving cursor; accept only after installation.
 * Allocation ID high-water marks survive checkout/branching.
 * Reset by creating a new history for New/Open. */
typedef struct xtc_history xtc_history;

/**
 * @brief Creates snapshot history with an independent copy of the initial project.
 *
 * @param p Project model; borrowed for this call.
 * @param out Receives the newly allocated object; caller owns it on success.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_history_create(const xtc_project * p, xtc_history ** out);
/**
 * @brief Releases all retained snapshots and history storage; accepts NULL.
 *
 * @param h Snapshot history handle.
 */
void xtc_history_destroy(xtc_history * h);
/**
 * @brief Appends a project snapshot, discarding redo states and evicting the oldest state if full.
 *
 * @param h Snapshot history handle.
 * @param p Project model; borrowed for this call.
 * @return XTC_OK on success, or an error code describing the failure.
 */
/* Reserve fixed-capacity snapshot storage before a user command mutates a
 * project or publishes a candidate. Idempotent; failure retains history/redo.
 * The next record uses this storage without allocating. It remains reserved
 * across rejected commands and is freed on record or history destruction.
 * All calls are serialized on the control thread, never in the callback. */
xtc_result xtc_history_reserve(xtc_history *history);
/* Available adjacent steps; metadata-only, no cloning/allocation. */
xtc_result xtc_history_counts(const xtc_history *history, size_t *undo_count, size_t *redo_count);
xtc_result xtc_history_record(xtc_history * h, const xtc_project * p);
/**
 * @brief Clones the adjacent undo or redo state without moving the history cursor.
 *
 * @param h Snapshot history handle.
 * @param redo Zero for undo, one for redo.
 * @param out Receives the newly allocated object; caller owns it on success.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_history_checkout(const xtc_history * h, int redo, xtc_project ** out);
/**
 * @brief Moves the history cursor after the checked-out project has been installed.
 *
 * @param h Snapshot history handle.
 * @param redo Zero for undo, one for redo.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_history_accept(xtc_history * h, int redo);

#ifdef __cplusplus
}
#endif

#endif