mlua-pulse 0.1.0

---@meta pulse

---`mlua-pulse` 的 LuaLS 注解文件。
---
---把本文件加入 LuaLS 的 `workspace.library` 后，编辑器即可为 `require("pulse")`
---返回的模块、链式编曲对象、导出选项和信息表提供补全与悬停说明。
local pulse = {}

---@alias pulse.NoteName string 音名，如 `"C4"`、`"F#3"`、`"Bb5"`。
---@alias pulse.Frequency number 赫兹频率，必须为正数。
---@alias pulse.Pattern number[]|string 鼓步进位置。数组使用 0 起始步号；字符串中 `x`、`X`、`1`、`*` 表示命中。
---@alias pulse.EffectOptions nil|string|table 效果选项。`nil` 使用默认值，字符串选择预置，表传入参数。
---@alias pulse.SynthOptions nil|string|number[]|table 合成器选项。加法合成可直接传谐波数组。
---@alias pulse.GeneratedValue number[]|number[][]|string 生成器输出。不同生成器会返回数字数组、矩阵或字符串。
---@alias pulse.NormalizeMode '"peak"'|'"rms"' 音频导出标准化模式；`"peak"` 对齐峰值，`"rms"` 对齐均方根响度并可设置峰值上限。
---@alias pulse.FilterType '"low_pass"'|'"high_pass"'|'"band_pass"'|'"notch"'|'"all_pass"'|'"moog"' 轨道滤波器类型名称。
---@alias pulse.DrumKit '"808"' 鼓机套件名称；当前提供 808 风格便捷构建器。

---@class pulse.ExportOptions
---离线导出选项。WAV/FLAC 会渲染音频，MIDI 只写事件数据，因此音频采样率和响度标准化不影响 MIDI。
---@field gpu? boolean 请求 `tunes` GPU 导出路径。未开启 crate 的 `gpu` 特性时会返回错误。
---@field sample_rate? integer WAV/FLAC 输出采样率，必须为正整数；常用 `44100` 或 `48000`。
---@field normalize? boolean|pulse.NormalizeMode|pulse.NormalizeOptions `true` 等价于峰值标准化；也可传 `"peak"`、`"rms"` 或详细表。
---@field target_db? number 标准化目标 dBFS。峰值模式默认 `-1.0`，RMS 模式默认 `-16.0`。
---@field true_peak_db? number RMS 标准化后的峰值上限 dBFS，默认 `-1.0`。
---@field peak_ceiling_db? number `true_peak_db` 的别名。
---@field flac_bits_per_sample? 16|24 标准化或显式位深 FLAC 的编码位深。默认 16-bit；需要更高余量时可设为 24。
---@field midi_velocity_gain? number MIDI Note On 力度增益，范围 `(0, 16]`。
---@field midi_min_velocity? number MIDI 非零力度下限，范围 `[0, 1]`。
---@field chunk_frames? integer `stream_pcm` 每次回调携带的帧数，必须为正整数；默认 `1024`。

---@class pulse.NormalizeOptions
---嵌套标准化选项，适合需要把模式和目标电平写在同一个表里的脚本。
---@field mode? pulse.NormalizeMode 省略时默认为 `"rms"`。
---@field target_db? number 目标响度或目标峰值，单位 dBFS。
---@field true_peak_db? number RMS 模式的峰值上限。
---@field peak_ceiling_db? number `true_peak_db` 的别名。

---@class pulse.EffectInfo
---效果目录项。由 `pulse.effect_info(name)` 返回，用于脚本自检、生成 UI 或写参数提示。
---@field name string 效果名称。
---@field category string 类别，如 `"time"`、`"dynamics"`、`"filter"`。
---@field scopes string[] 可用范围，包含 `"track"`、`"master"` 或二者。
---@field parameters string[] 参数名列表。
---@field presets string[] 预置名列表。

---@class pulse.SynthInfo
---合成器目录项。由 `pulse.synth_info(name)` 返回，描述算法、别名、预置和可调参数。
---@field name string 合成器规范名称。
---@field category string 合成类别。
---@field parameters string[] 参数名列表。
---@field presets string[] 预置名列表。
---@field aliases string[] 可作为 `sequence:synth(...)` 第一个参数的别名。

---@class pulse.GeneratorInfo
---算法生成器目录项。由 `pulse.generator_info(name)` 返回，方便脚本根据参数清单构造生成器调用。
---@field name string 生成器名称。
---@field category string 类别，如 `"mathematical"`、`"generative"`、`"musical"`、`"rhythmic"`。
---@field output string 输出类型说明，如 `"integers"`、`"numbers"`、`"integer_matrix"`、`"text"`。
---@field parameters string[] 参数名列表。空数组表示该预置不需要选项。

---@class pulse.GeneratorOptions
---生成器选项表。不同生成器读取不同字段；可通过 `pulse.generator_info(name)` 查询。
---@field length? integer 输出长度。
---@field start? number|integer 起始值。
---@field step? number|integer 步长。
---@field steps? integer 步数或节奏网格长度。
---@field pulses? integer 欧几里得节奏命中数。
---@field base? integer Van der Corput 序列进制。
---@field r? number 混沌映射参数。
---@field initial? number 初始值。
---@field axiom? string L 系统初始串。
---@field rules? table<string,string> L 系统重写规则。键必须为单个字符。
---@field iterations? integer 迭代次数。
---@field pattern? string L 系统文本，可交给 `l_system_values`。
---@field width? integer 元胞自动机宽度。
---@field generations? integer 元胞自动机代数。
---@field rule? integer 元胞自动机规则号。
---@field fundamental? number 谐波序列基频。

---@alias pulse.PcmCallback fun(chunk:pulse.PcmChunk) 流式 PCM 回调函数；每次接收一个 `pulse.PcmChunk` userdata，不能假定它是 table 或 string。

---@class pulse.PcmChunk
---流式 PCM 块。它是 userdata，不是 Lua table；用于避免把大块原始采样复制成表。
local PcmChunk = {}

---返回本块包含的音频帧数。一个帧包含左右声道各一个采样。
---@return integer frames 当前块中的帧数。
function PcmChunk:frames() end

---返回本块包含的交错采样数量。
---@return integer samples 左右声道交错后的采样总数。
function PcmChunk:samples() end

---返回本块 PCM 字节数。
---@return integer bytes 当前块按 `i16le` 编码后的字节数。
function PcmChunk:bytes() end

---返回渲染采样率。
---@return integer sample_rate 当前流的采样率，单位 Hz。
function PcmChunk:sample_rate() end

---返回声道数；当前固定为 `2`。
---@return integer channels 当前流的声道数。
function PcmChunk:channels() end

---返回 PCM 格式；当前固定为 little-endian signed 16-bit，即 `"i16le"`。
---@return '"i16le"' format 原始 PCM 的样本格式。
function PcmChunk:format() end

---读取第 `index` 个交错采样，使用 1 起始索引；越界返回 `nil`。
---@param index integer 1 起始的交错采样索引；奇偶位置对应左右声道。
---@return integer|nil sample 有符号 16-bit 采样值；索引越界时为 `nil`。
function PcmChunk:sample(index) end

---@class pulse.Sequence
---旋律或和声序列。所有 setter 都返回自身，适合链式调用。
local Sequence = {}

---用单音频率数组替换序列内容；会清空之前设置的和弦。
---@param notes pulse.Frequency[] 按时间顺序播放的单音频率数组。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:notes(notes) end

---用复音事件替换序列内容；每个和弦最多 8 个频率。
---@param chords pulse.Frequency[][] 按时间顺序播放的和弦数组，每个子数组是一组同时发声的频率。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:chords(chords) end

---设置每个音符或和弦事件的时值，单位为拍，数量必须与事件数一致。
---@param durations number[] 每个事件的拍长；例如 `0.25` 是十六分音符，`1.0` 是一拍。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:durations(durations) end

---设置 `tunes` 乐器别名，可通过 `pulse.instruments()` 查询。
---@param instrument string 乐器别名；未知名称会在导出或渲染时返回错误。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:instrument(instrument) end

---设置序列在作品或乐句中的起始偏移，单位为拍。
---@param start_at number 非负数。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:at(start_at) end

---设置轨道音量。大多数编曲建议保持在 `0.2..1.0`，最高允许 `2.0`。
---@param volume number 范围 `[0, 2]`。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:volume(volume) end

---设置立体声声像。
---@param pan number 范围 `[-1, 1]`，`-1` 左，`1` 右。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:pan(pan) end

---设置音符力度，会影响音频合成和 MIDI Note On 力度。
---@param velocity number 范围 `[0, 1]`。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:velocity(velocity) end

---添加轨道级效果。`filter` 只能放在轨道级，不能作为 master 效果。
---@param name string 效果名，如 `"delay"`、`"reverb"`、`"filter"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:effect(name, options) end

---选择显式合成算法，覆盖乐器默认音色的部分合成参数。
---@param name string 合成器名或别名，如 `"fm"`、`"additive"`、`"karplus_strong"`、`"granular"`。
---@param options? pulse.SynthOptions 合成预置、谐波数组或参数表；省略时使用算法默认值。
---@return pulse.Sequence sequence 当前序列自身，用于继续链式设置。
function Sequence:synth(name, options) end

---返回移调后的新序列，不修改原序列。
---@param semitones integer 半音数。
---@return pulse.Sequence transposed 移调后的新序列。
function Sequence:transpose(semitones) end

---@class pulse.SampleClip
---离线采样片段。所有变换都会在加入作品或乐句时展开到导出的音频中。
local SampleClip = {}

---设置播放速率。大于 1 更快更高，小于 1 更慢更低。
---@param playback_rate number 正数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:rate(playback_rate) end

---设置采样增益。
---@param gain number 非负数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:gain(gain) end

---以半音为单位调整音高。
---@param semitones number 音高偏移量；正数升高，负数降低。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:pitch_shift(semitones) end

---调整时间长度而尽量保持音高。
---@param factor number 正数；`1.25` 表示更长。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:time_stretch(factor) end

---设置采样片段在作品或乐句中的起始偏移。
---@param start_at number 非负数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:at(start_at) end

---选择源音频中的时间范围，单位为秒。
---@param start number 非负数。
---@param finish number 必须大于 `start`。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:slice(start, finish) end

---反向播放所选源音频范围。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:reverse() end

---把所选源音频离线循环到固定时长，单位为秒。
---@param duration number 正数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:loop_for(duration) end

---对采样片段做源峰值标准化，再应用淡入淡出和最终增益。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:normalize() end

---添加淡入，单位为秒。
---@param duration number 非负数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:fade_in(duration) end

---添加淡出，单位为秒。
---@param duration number 非负数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:fade_out(duration) end

---设置采样片段导入作品后的轨道名称，方便导出和调试。
---@param track_name string 采样轨道名称；空白名称会回退到默认名称。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:track(track_name) end

---设置采样轨道音量。
---@param volume number 范围 `[0, 2]`；建议混音时从 `0.2..1.0` 起步。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:volume(volume) end

---设置采样轨道声像。
---@param pan number 范围 `[-1, 1]`，`-1` 左，`1` 右。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:pan(pan) end

---给采样轨道添加轨道级效果；音频导出、播放和 PCM 流会渲染这些效果。
---@param name string 效果名，如 `"delay"`、`"reverb"`、`"filter"`、`"compressor"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.SampleClip sample_clip 当前采样片段自身，用于继续链式设置。
function SampleClip:effect(name, options) end

---@class pulse.MidiClip
---可编排的导入 MIDI 片段。它可以加入作品或段落；音频导出会渲染其音符、混音和效果，MIDI 导出只保留 MIDI 文件能表达的事件与控制信息。
local MidiClip = {}

---设置 MIDI 片段在作品或段落中的起始偏移。
---@param start_at number 非负数。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:at(start_at) end

---设置导入 MIDI 轨道合并后的轨道名前缀。
---@param track_name string 轨道名前缀；多轨 MIDI 会自动追加编号。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:track(track_name) end

---设置导入 MIDI 轨道的音量倍率。
---@param volume number 范围 `[0, 2]`；会乘以源 MIDI 轨道音量。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:volume(volume) end

---覆盖导入 MIDI 轨道的立体声声像。
---@param pan number 范围 `[-1, 1]`，`-1` 左，`1` 右。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:pan(pan) end

---设置导入 MIDI 素材在片段内部的总播放次数。
---@param repeat_times integer 总播放次数，必须大于 0；`1` 表示只播放一遍。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:repeat_times(repeat_times) end

---给导入 MIDI 轨道添加轨道级效果；这些效果会进入音频导出、播放和 PCM 流，但不会写入 MIDI 文件。
---@param name string 效果名，如 `"reverb"`、`"chorus"`、`"eq"`、`"compressor"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.MidiClip midi_clip 当前 MIDI 片段自身，用于继续链式设置。
function MidiClip:effect(name, options) end

---@class pulse.DrumGrid
---步进鼓网格。数组模式使用 0 起始步号；字符串模式更适合写 808/909 风格循环。
local DrumGrid = {}

---设置导出的鼓轨名称。
---@param track_name string 导出和调试时使用的鼓轨名称。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:track(track_name) end

---设置网格步数。
---@param steps integer 正数。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:steps(steps) end

---设置每步时值，单位为拍。
---@param duration number 正数。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:step_duration(duration) end

---添加一种鼓声及其命中模式。
---@param drum string 鼓声名，可通过 `pulse.drums()` 查询。
---@param pattern pulse.Pattern 命中步号数组或步进字符串。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:sound(drum, pattern) end

---添加重音步。命中的步会提高鼓事件力度。
---@param pattern pulse.Pattern 需要加重音的步号数组或步进字符串。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:accent(pattern) end

---逐步设置力度，按步循环应用。
---@param velocities number[] 范围通常为 `[0, 1]`。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:velocity(velocities) end

---设置鼓轨音量。
---@param volume number 范围 `[0, 2]`。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:volume(volume) end

---设置鼓轨声像。
---@param pan number 范围 `[-1, 1]`。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:pan(pan) end

---设置鼓网格总播放次数。
---@param repeats integer 总播放次数，必须大于 0；`1` 表示只播放一遍。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:repeat_times(repeats) end

---添加轨道级效果。
---@param name string 效果名，如 `"delay"`、`"compressor"`、`"filter"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.DrumGrid grid 当前鼓网格自身，用于继续链式设置。
function DrumGrid:effect(name, options) end

---@class pulse.DrumMachine
---808 鼓机风格的便捷构建器，最终通过 `:grid()` 转为 `pulse.DrumGrid`。
local DrumMachine = {}

---设置鼓机网格步数；通常 16 表示一小节十六步。
---@param steps integer 鼓机步数，必须为正整数。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:steps(steps) end

---设置鼓机每步时值，单位为拍；例如 `0.25` 表示十六分音符步长。
---@param duration number 每步拍长，必须为正数。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:step_duration(duration) end

---添加 808 kick 命中模式。
---@param pattern pulse.Pattern kick 的命中步号数组或步进字符串。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:kick(pattern) end

---添加 808 snare 命中模式。
---@param pattern pulse.Pattern snare 的命中步号数组或步进字符串。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:snare(pattern) end

---添加 808 closed hi-hat 命中模式。
---@param pattern pulse.Pattern closed hi-hat 的命中步号数组或步进字符串。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:hihat(pattern) end

---添加 808 open hi-hat 命中模式。
---@param pattern pulse.Pattern open hi-hat 的命中步号数组或步进字符串。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:open_hihat(pattern) end

---添加 808 clap 命中模式。
---@param pattern pulse.Pattern clap 的命中步号数组或步进字符串。
---@return pulse.DrumMachine machine 当前鼓机自身，用于继续链式设置。
function DrumMachine:clap(pattern) end

---结束鼓机构建并返回可加入作品或乐句的鼓网格。
---@return pulse.DrumGrid grid 由当前鼓机模式生成的鼓网格。
function DrumMachine:grid() end

---@class pulse.Phrase
---可复用段落，能包含旋律序列、鼓网格和采样片段，并按顺序重复展开。
local Phrase = {}

---向段落追加一个旋律或和声序列。
---@param sequence pulse.Sequence 要放入段落时间线的旋律或和声序列。
---@return pulse.Phrase phrase 当前段落自身，用于继续链式设置。
function Phrase:add(sequence) end

---向段落追加一个鼓网格；段落重复时鼓网格会随段落一起展开。
---@param grid pulse.DrumGrid 要放入段落时间线的鼓网格。
---@return pulse.Phrase phrase 当前段落自身，用于继续链式设置。
function Phrase:add_drum_grid(grid) end

---向段落追加一个采样片段；适合把短音频素材放进可重复段落中。
---@param sample_clip pulse.SampleClip 要放入段落时间线的离线采样片段。
---@return pulse.Phrase phrase 当前段落自身，用于继续链式设置。
function Phrase:add_sample(sample_clip) end

---向段落追加一个导入 MIDI 片段；段落重复时 MIDI 轨道会随段落一起展开。
---@param midi pulse.ImportedMidi|pulse.MidiClip 要放入段落时间线的导入 MIDI 或已编排 MIDI 片段。
---@return pulse.Phrase phrase 当前段落自身，用于继续链式设置。
function Phrase:add_midi(midi) end

---设置段落的总播放次数。
---@param repeat_times integer 总播放次数，必须大于 0；`1` 表示只播放一遍。
---@return pulse.Phrase phrase 当前段落自身，用于继续链式设置。
function Phrase:repeat_times(repeat_times) end

---@class pulse.Song
---完整作品。导出前会把序列、鼓网格、乐句和采样片段展开成 `tunes` mixer。
local Song = {}

---设置速度，单位 BPM。
---@param bpm number 正数。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:tempo(bpm) end

---向作品直接追加一个旋律或和声序列。
---@param sequence pulse.Sequence 要放入作品时间线的旋律或和声序列。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:add(sequence) end

---向作品直接追加一个鼓网格。
---@param grid pulse.DrumGrid 要放入作品时间线的鼓网格。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:add_drum_grid(grid) end

---向作品追加一个可重复段落；多个段落会按加入顺序接在时间线上。
---@param phrase pulse.Phrase 要展开到作品时间线中的段落。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:add_phrase(phrase) end

---向作品直接追加一个采样片段。
---@param sample_clip pulse.SampleClip 要放入作品时间线的离线采样片段。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:add_sample(sample_clip) end

---向作品直接追加一个导入 MIDI 片段；它会参与 WAV、FLAC、PCM 和播放渲染，并在 MIDI 导出中保留可表达事件。
---@param midi pulse.ImportedMidi|pulse.MidiClip 要放入作品时间线的导入 MIDI 或已编排 MIDI 片段。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:add_midi(midi) end

---添加 master 级效果。`filter` 不支持 master；请使用 `eq` 做 master 频率整形。
---@param name string master 效果名，如 `"reverb"`、`"limiter"`、`"eq"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.Song song 当前作品自身，用于继续链式设置。
function Song:master_effect(name, options) end

---按扩展名导出：`.wav`、`.flac`、`.mid`、`.midi`。
---@param path string 目标文件路径；扩展名决定导出格式。
---@param options? pulse.ExportOptions 导出采样率、GPU、响度标准化和 MIDI 力度等选项。
function Song:export(path, options) end

---导出 WAV 文件；普通路径委托 `tunes`，启用标准化时会先渲染缓冲再写入。
---@param path string 目标 WAV 文件路径。
---@param options? pulse.ExportOptions WAV 采样率、GPU 和响度标准化等选项。
function Song:export_wav(path, options) end

---导出 FLAC 文件；可用 `flac_bits_per_sample` 控制标准化/手动编码路径的位深。
---@param path string 目标 FLAC 文件路径。
---@param options? pulse.ExportOptions FLAC 采样率、GPU、响度标准化和位深等选项。
function Song:export_flac(path, options) end

---导出 MIDI 文件；音频标准化不影响 MIDI，可用 MIDI 力度选项提升 Note On 力度。
---@param path string 目标 MIDI 文件路径，通常以 `.mid` 或 `.midi` 结尾。
---@param options? pulse.ExportOptions MIDI 导出选项；主要使用 `midi_velocity_gain` 和 `midi_min_velocity`。
function Song:export_midi(path, options) end

---把作品离线渲染为原始 PCM，并按块把 `pulse.PcmChunk` userdata 传给回调。
---也可写作 `Song:stream_pcm(options, callback)`，便于先声明块大小和采样率。
---@overload fun(self: pulse.Song, options: pulse.ExportOptions, callback: pulse.PcmCallback): integer
---@param callback pulse.PcmCallback 每个 PCM 块到达时调用；参数是 userdata，不是 table 或 string。
---@param options? pulse.ExportOptions 流式渲染采样率、GPU、响度标准化和块大小等选项。
---@return integer chunks 已发送的块数。
function Song:stream_pcm(callback, options) end

---立即播放作品。无音频设备或无声卡环境中可能返回播放错误。
function Song:play() end

---按指定速率播放作品。
---@param rate number 正数。
function Song:play_at_rate(rate) end

---@class pulse.ImportedMidi
---由 `pulse.import_midi(path)` 得到的 MIDI mixer 包装，可重新导出音频或 MIDI。
local ImportedMidi = {}

---把导入 MIDI 转成可编排片段并设置起始偏移。
---@param start_at number 非负数。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:at(start_at) end

---把导入 MIDI 转成可编排片段并设置轨道名前缀。
---@param track_name string 轨道名前缀；多轨 MIDI 会自动追加编号。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:track(track_name) end

---把导入 MIDI 转成可编排片段并设置音量倍率。
---@param volume number 范围 `[0, 2]`。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:volume(volume) end

---把导入 MIDI 转成可编排片段并覆盖声像。
---@param pan number 范围 `[-1, 1]`，`-1` 左，`1` 右。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:pan(pan) end

---把导入 MIDI 转成可编排片段并设置内部总播放次数。
---@param repeat_times integer 总播放次数，必须大于 0；`1` 表示只播放一遍。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:repeat_times(repeat_times) end

---把导入 MIDI 转成可编排片段并添加轨道级效果。
---@param name string 效果名，如 `"reverb"`、`"chorus"`、`"eq"`、`"compressor"`。
---@param options? pulse.EffectOptions 效果预置或参数表；省略时使用默认参数。
---@return pulse.MidiClip midi_clip 新建的可编排 MIDI 片段。
function ImportedMidi:effect(name, options) end

---按扩展名重新导出导入的 MIDI mixer，支持 `.wav`、`.flac`、`.mid`、`.midi`。
---@param path string 目标文件路径；扩展名决定导出格式。
---@param options? pulse.ExportOptions 导出采样率、GPU、响度标准化和 MIDI 力度等选项。
function ImportedMidi:export(path, options) end

---把导入的 MIDI mixer 渲染并导出为 WAV。
---@param path string 目标 WAV 文件路径。
---@param options? pulse.ExportOptions WAV 采样率、GPU 和响度标准化等选项。
function ImportedMidi:export_wav(path, options) end

---把导入的 MIDI mixer 渲染并导出为 FLAC。
---@param path string 目标 FLAC 文件路径。
---@param options? pulse.ExportOptions FLAC 采样率、GPU、响度标准化和位深等选项。
function ImportedMidi:export_flac(path, options) end

---把导入的 MIDI mixer 重新导出为 MIDI 文件。
---@param path string 目标 MIDI 文件路径，通常以 `.mid` 或 `.midi` 结尾。
---@param options? pulse.ExportOptions MIDI 导出选项；主要使用 `midi_velocity_gain` 和 `midi_min_velocity`。
function ImportedMidi:export_midi(path, options) end

---把导入的 MIDI mixer 渲染为原始 PCM，并按块把 `pulse.PcmChunk` userdata 传给回调。
---也可写作 `ImportedMidi:stream_pcm(options, callback)`，与作品 PCM 流保持一致。
---@overload fun(self: pulse.ImportedMidi, options: pulse.ExportOptions, callback: pulse.PcmCallback): integer
---@param callback pulse.PcmCallback 每个 PCM 块到达时调用；参数是 userdata，不是 table 或 string。
---@param options? pulse.ExportOptions 流式渲染采样率、GPU、响度标准化和块大小等选项。
---@return integer chunks 已发送的块数。
function ImportedMidi:stream_pcm(callback, options) end

---@class pulse.PlaybackEngine
---实时播放入口。离线导出仍应优先使用 `song:export_*`。
local PlaybackEngine = {}

---播放作品或导入的 MIDI，适合简单预览；该调用不返回可控制句柄。
---@param playable pulse.Song|pulse.ImportedMidi 要实时预览的作品或导入 MIDI。
function PlaybackEngine:play(playable) end

---实时播放作品或导入的 MIDI，并返回可暂停、恢复、停止的句柄。
---@param playable pulse.Song|pulse.ImportedMidi 要实时播放的作品或导入 MIDI。
---@return pulse.PlaybackHandle handle 可继续控制音量、声像、速率和播放状态的句柄。
function PlaybackEngine:play_realtime(playable) end

---循环播放作品或导入的 MIDI，并返回控制句柄。
---@param playable pulse.Song|pulse.ImportedMidi 要循环播放的作品或导入 MIDI。
---@return pulse.PlaybackHandle handle 可继续控制循环播放状态的句柄。
function PlaybackEngine:play_looping(playable) end

---以指定速率播放作品或导入的 MIDI；速率必须为正数。
---@param playable pulse.Song|pulse.ImportedMidi 要按变速倍率播放的作品或导入 MIDI。
---@param rate number 正数。
function PlaybackEngine:play_at_rate(playable, rate) end

---以指定速率实时播放，并返回可继续调节的播放句柄。
---@param playable pulse.Song|pulse.ImportedMidi 要按变速倍率实时播放的作品或导入 MIDI。
---@param rate number 正数。
---@return pulse.PlaybackHandle handle 可继续控制音量、声像、速率和播放状态的句柄。
function PlaybackEngine:play_realtime_at_rate(playable, rate) end

---@class pulse.PlaybackHandle
---实时播放句柄。控制方法返回句柄自身，因此可以链式调用。
local PlaybackHandle = {}

---停止当前播放。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:stop() end

---设置实时播放音量。
---@param volume number 范围 `[0, 1]`。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:volume(volume) end

---设置实时播放声像。
---@param pan number 范围 `[-1, 1]`。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:pan(pan) end

---设置实时播放速率。
---@param rate number 正数。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:rate(rate) end

---暂停当前播放。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:pause() end

---恢复已暂停的播放。
---@return pulse.PlaybackHandle handle 当前播放句柄自身，用于继续链式控制。
function PlaybackHandle:resume() end

---把音名解析为频率，便于在脚本里直接写 `pulse.note("C4")`。
---@param name pulse.NoteName 音名字符串，支持升降号和八度号。
---@return pulse.Frequency frequency 对应的十二平均律频率。
function pulse.note(name) end

---返回所有可传给 `pulse.scale(root, mode)` 的调式名和别名。
---@return string[] modes 调式名列表，包含大小调和希腊调式。
function pulse.modes() end

---返回所有可传给 `pulse.chord(root, kind)` 的和弦类型名和别名。
---@return string[] chord_kinds 和弦类型名列表。
function pulse.chord_kinds() end

---生成音阶频率数组，包含八度重复音。
---@param root pulse.NoteName 音阶根音，如 `"C4"` 或 `"F#3"`。
---@param mode string 支持 major/minor 及 ionian、dorian、phrygian、lydian、mixolydian、aeolian、locrian。
---@return pulse.Frequency[] frequencies 根音到八度重复音的频率数组。
function pulse.scale(root, mode) end

---生成和弦频率数组。
---@param root pulse.NoteName 和弦根音，如 `"C4"` 或 `"Bb3"`。
---@param kind string 如 `"maj"`、`"min"`、`"maj7"`、`"min7"`、`"dominant7"`、`"dim"`、`"aug"`。
---@return pulse.Frequency[] frequencies 和弦各音的频率数组。
function pulse.chord(root, kind) end

---移调单个频率或频率数组。
---@generic T: number|number[]
---@param value T 要移调的频率或频率数组。
---@param semitones integer 半音偏移量；正数升高，负数降低。
---@return T transposed 与输入形状一致的移调结果。
function pulse.transpose(value, semitones) end

---把频率转换为最接近的 MIDI 音符号。
---@param frequency pulse.Frequency 要转换的频率，单位 Hz。
---@return integer midi_note 最接近输入频率的 MIDI 音符号。
function pulse.frequency_to_midi_note(frequency) end

---把 MIDI 音符号转换为十二平均律频率。
---@param note integer MIDI 音符号，范围 `0..127`。
---@return pulse.Frequency frequency 对应的十二平均律频率。
function pulse.midi_note_to_frequency(note) end

---返回统一导出入口支持的文件扩展名。
---@return string[] 支持的导出扩展名：`wav`、`flac`、`mid`、`midi`。
function pulse.export_formats() end

---返回所有 Lua 可用乐器别名。
---@return string[] 当前 `tunes 1.1.0` 乐器别名目录。
function pulse.instruments() end

---返回所有 Lua 可用鼓声别名，包含分层鼓别名。
---@return string[] 当前鼓声目录，含 `mlua-pulse` 分层鼓别名。
function pulse.drums() end

---返回所有 Lua 可用效果名称。
---@return string[] 效果名称目录。
function pulse.effects() end

---查询单个效果的参数、预置和可用范围。
---@param name string 效果名，可通过 `pulse.effects()` 查询。
---@return pulse.EffectInfo info 效果信息表，包含类别、参数、预置和可用范围。
function pulse.effect_info(name) end

---返回所有 Lua 可用合成算法名称。
---@return string[] 合成器名称目录。
function pulse.synths() end

---查询单个合成算法的参数、预置和别名。
---@param name string 合成器名或别名。
---@return pulse.SynthInfo info 合成器信息表，包含类别、参数、预置和别名。
function pulse.synth_info(name) end

---返回所有 Lua 可调用算法生成器名称。
---@return string[] 生成器名称目录。
function pulse.generators() end

---查询单个算法生成器的类别、输出类型和参数名。
---@param name string 生成器名称，可通过 `pulse.generators()` 查询。
---@return pulse.GeneratorInfo info 生成器信息表，包含类别、输出类型和参数名。
function pulse.generator_info(name) end

---调用算法生成器，返回数字数组、矩阵或文本，具体形状取决于生成器。
---@param name string 生成器名称，如 `"fibonacci"`、`"primes"`、`"l_system"`。
---@param options? pulse.GeneratorOptions 生成器参数表；具体字段由生成器决定。
---@return pulse.GeneratedValue value 生成结果，可能是数字数组、矩阵或字符串。
function pulse.generate(name, options) end

---把有限数字数组归一化到指定范围。
---@param values number[] 要映射的输入数字数组。
---@param min number 输出范围最小值。
---@param max number 输出范围最大值。
---@return number[] normalized 映射到 `[min, max]` 的新数组。
function pulse.normalize(values, min, max) end

---把生成器数值映射到指定音阶频率。
---@param values number[] 要映射的输入数字数组。
---@param scale string 支持 major/minor、五声音阶、blues、chromatic、whole_tone 及希腊调式等。
---@param root pulse.NoteName 映射音阶根音。
---@param octaves integer 正整数。
---@return pulse.Frequency[] frequencies 映射后的频率旋律数组。
function pulse.map_to_scale(values, scale, root, octaves) end

---生成欧几里得节奏命中步号，使用 0 起始索引。
---@param pulses integer 命中数量。
---@param steps integer 总步数。
---@return integer[] hits 0 起始的命中步号数组。
function pulse.euclidean(pulses, steps) end

---生成二进制欧几里得节奏模式。
---@param pulses integer 命中数量。
---@param steps integer 总步数。
---@return integer[] pattern 长度为 `steps` 的 0/1 模式数组。
function pulse.euclidean_pattern(pulses, steps) end

---返回命名节奏，如 `"four_on_floor"`、`"tresillo"`、`"cinquillo"`。
---@param name string 命名节奏名称。
---@return integer[] hits 0 起始的命中步号数组。
function pulse.pattern(name) end

---创建一个空鼓网格。
---@return pulse.DrumGrid grid 新建的鼓网格。
function pulse.drum_grid() end

---创建 808 鼓机便捷构建器。
---@param kit pulse.DrumKit 鼓机套件名称；当前支持 `"808"`。
---@return pulse.DrumMachine machine 新建的鼓机便捷构建器。
function pulse.drum_machine(kit) end

---创建空旋律/和声序列。
---@return pulse.Sequence sequence 新建的空序列。
function pulse.sequence() end

---创建空段落。
---@return pulse.Phrase phrase 新建的空段落。
function pulse.phrase() end

---创建一个离线采样片段引用；真正读取文件发生在导出或渲染时。
---@param path string 源音频文件路径。
---@return pulse.SampleClip sample_clip 新建的采样片段引用。
function pulse.sample(path) end

---创建空作品。
---@return pulse.Song song 新建的空作品。
function pulse.song() end

---创建实时播放入口。
---@return pulse.PlaybackEngine engine 新建的播放入口。
function pulse.playback() end

---导入 MIDI 文件，得到可重新导出音频或 MIDI 的包装对象。
---@param path string 源 MIDI 文件路径。
---@return pulse.ImportedMidi imported 导入后的 MIDI 包装对象。
function pulse.import_midi(path) end

---尝试把可渲染对象流式输出为原始 PCM。支持 `pulse.Song` 和 `pulse.ImportedMidi`；不支持的值直接返回 `nil`，不会调用回调。
---也可写作 `pulse.stream_pcm(playable, options, callback)`。
---@overload fun(playable: any, options: pulse.ExportOptions, callback: pulse.PcmCallback): integer|nil
---@param playable any 可能支持流式渲染的值；目前支持作品和导入 MIDI。
---@param callback pulse.PcmCallback 每个 PCM 块到达时调用；参数是 userdata，不是 table 或 string。
---@param options? pulse.ExportOptions 流式渲染采样率、GPU、响度标准化和块大小等选项。
---@return integer|nil chunks 已发送的块数；不支持流式渲染的值会返回 `nil`。
function pulse.stream_pcm(playable, callback, options) end

return pulse