编解码基础库

AudioIO编解码基础库用于音频资源的获取，能力包括：

• 音频编解码：通过解码可获取音频原始数据，通过编码可将音频原始数据写入压缩/非压缩音频文件中

• MIDI读取：可读取midi文件中各midi事件

解码

头文件：

#include "sami_core_audio_io.h"

接入步骤：

1. 创建解码器

函数名：

int SAMICoreFileSourceCreate(SAMICoreFileSource* fileSource, 
                             const char* inputPath);

作用：
根据传入音频文件路径创建解码器，可通过解码器获取音频信息、读取音频数据
参数说明：

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICoreFileSource fileSource;
int ret = SAMICoreFileSourceCreate(&fileSource, input_file);
if(ret != SAMI_OK) {
    std::cout << "create file source fail!" << std::endl;
}

2. 获取音频信息

获取采样率

函数名：

size_t SAMICoreFileSourceGetSampleRate(SAMICoreFileSource fileSource);

作用：
通过解码器获取音频文件采样率，采样率概念可见名次解释
参数说明：

返回值：
音频文件采样率
示例：

size_t sample_rate = SAMICoreFileSourceGetSampleRate(fileSource);

获取声道数

函数名：

size_t SAMICoreFileSourceGetNumChannel(SAMICoreFileSource fileSource);

作用：
通过解码器获取音频文件声道数，声道数概念可见名次解释
参数说明：

返回值：
音频文件声道数
示例：

size_t num_channels = SAMICoreFileSourceGetNumChannel(fileSource);

获取位深度

函数名：

size_t SAMICoreFileSourceGetNumBit(SAMICoreFileSource fileSource);

作用：
通过解码器获取音频文件位深度，位深度概念可见名次解释
参数说明：

返回值：
音频文件位深度
示例：

size_t num_bit = SAMICoreFileSourceGetNumBit(fileSource);

获取采样点数

函数名：

size_t SAMICoreFileSourceGetNumFrames(SAMICoreFileSource fileSource);

作用：
通过解码器获取音频文件单个通道的采样点数
参数说明：

返回值：
音频文件采样点数，双声道时返回单个通道的采样点数
示例：

size_t num_samples = SAMICoreFileSourceGetNumFrames(fileSource);

获取当前读取位置

函数名：

size_t SAMICoreFileSourceGetPosition(SAMICoreFileSource fileSource);

作用：
通过解码器获取当前读取的采样点位置
参数说明：

返回值：
解码器当前读取的采样点位置，双声道时返回一个声道的采样点位置
示例：

size_t position = SAMICoreFileSourceGetPosition(fileSource);

3. 设置读取位置

函数名：

bool SAMICoreFileSourceSeek(SAMICoreFileSource fileSource, size_t position);

作用：
通过解码器设置后续需要读取的开始位置
参数说明：

返回值：
true成功，false失败
示例：

bool ret = SAMICoreFileSourceSeek(fileSource, position);

4. 读取音频原始数据

函数名：

size_t SAMICoreFileSourceRead(SAMICoreFileSource fileSource, 
                              float* buffer, 
                              size_t frame_num);

作用：
通过解码器读取音频原始数据
参数说明：

返回值：
成功读取的采样点数
示例：

int real_size = SAMICoreFileSourceRead(fileSource, interleave_data, num_samples);

5. 销毁解码器

函数名：

void SAMICoreFileSourceDestory(SAMICoreFileSource fileSource);

作用：
销毁解码器
参数说明：

示例：

SAMICoreFileSourceDestory(fileSource);

完整示例

#include "sami_core_audio_io.h"

const char* input_file = "/path/file";
SAMICoreFileSource fileSource;
int ret = SAMICoreFileSourceCreate(&fileSource, input_file);
if(ret != SAMI_OK) {
    std::cout << "create file source fail!" << std::endl;
    return -1;
}

bool ret = SAMICoreFileSourceSeek(fileSource, position);

size_t num_channels = SAMICoreFileSourceGetNumChannel(fileSource);
size_t sample_rate = SAMICoreFileSourceGetSampleRate(fileSource);
size_t num_samples = SAMICoreFileSourceGetNumFrames(fileSource);
float *interleave_data = new float[num_samples * num_channels];
int real_size = SAMICoreFileSourceRead(fileSource, interleave_data, num_samples);
SAMICoreFileSourceDestory(fileSource);

delete[] interleave_data;

编码

头文件：

#include "sami_core_audio_io.h"

接入步骤：

1. 创建编码器

函数名：

int SAMICoreAudioEncoderCreate(SAMICoreAudioEncoder* audioEncoder, void* settings);

作用：
根据传入编码设置创建编码器
参数说明：

• SAMICoreAudioEncoderSettings

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICoreAudioEncoderSettings settings;
memset(&settings, 0, sizeof(SAMICoreAudioEncoderSettings));
settings.format = SAMICoreAudioEncoderFormat::kWav_F32;
settings.acc = SAMICoreAudioEncoderAcceleration::kSoftware;
settings.threading = SAMICoreAudioEncoderThreading::kSingleThreaded;
settings.num_threads = 0;
SAMICoreAudioEncoder audioEncoder;
ret = SAMICoreAudioEncoderCreate(&audioEncoder, &settings);
if(ret != SAMI_OK) {
    return -1;
}

2. 打开音频文件

函数名：

int SAMICoreAudioEncoderOpen(SAMICoreAudioEncoder audioEncoder, 
                             const char* output_path,
                             int sample_rate, 
                             int num_channels, 
                             long long bit_rate);

作用：
传入目标路径、采样率、声道数、码率，通过编码器打开目标音频文件
参数说明：

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

ret = SAMICoreAudioEncoderOpen(audioEncoder, output_file, sample_rate, num_channels, bit_rate);
if(ret != SAMI_OK) {
    return -1;
}

3. 获取文件信息

获取文件状态

函数名：

bool SAMICoreAudioEncoderIsOpen(SAMICoreAudioEncoder audioEncoder);

作用：
通过解码器获取当前音频文件状态
参数说明：

返回值：
目标音频文件当前状态
示例：

bool is_open = SAMICoreAudioEncoderIsOpen(audioEncoder);

获取采样率

函数名：

int SAMICoreAudioEncoderGetSampleRate(SAMICoreAudioEncoder audioEncoder);

作用：
通过解码器获取音频文件采样率
参数说明：

返回值：
目标音频文件采样率
示例：

int sample_rate = SAMICoreAudioEncoderGetSampleRate(audioEncoder);

获取声道数

函数名：

int SAMICoreAudioEncoderGetNumChannels(SAMICoreAudioEncoder audioEncoder);

作用：
通过解码器获取音频文件声道数
参数说明：

返回值：
目标音频文件声道数
示例：

int num_channels = SAMICoreAudioEncoderGetNumChannels(audioEncoder);

4. 写入音频原始数据

Interleave格式写入

函数名：

long long SAMICoreAudioEncoderWriteInterleaveData(SAMICoreAudioEncoder audioEncoder,
                                                  const float* interleave_data, 
                                                  int num_channels,
                                                  long long num_sample_per_channel);

作用：
通过编码器将Interleave格式音频数据写入文件，Interleave格式可见名次解释
参数说明：

返回值：
成功写入的采样点数
示例：

int write_size = SAMICoreAudioEncoderWriteInterleaveData(audioEncoder, interleave_data, num_channels, num_samples);

Planar格式写入

函数名：

long long SAMICoreAudioEncoderWritePlanarData(SAMICoreAudioEncoder audioEncoder,
                                              const float* const* planar_data, 
                                              int num_channels,
                                              long long num_sample_per_channel);

作用：
通过编码器将planar格式音频数据写入文件，planar格式可见名次解释
参数说明：

返回值：
成功写入的采样点数，双声道时返回单声道成功写入的采样点数
示例：

int write_size = SAMICoreAudioEncoderWritePlanarData(audioEncoder, planar_data, num_channels, num_samples);

5. 关闭编码器

函数名：

void SAMICoreAudioEncoderClose(SAMICoreAudioEncoder audioEncoder);

作用：
关闭编码器
参数说明：

示例：

SAMICoreAudioEncoderClose(audioEncoder);

6. 销毁编码器

函数名：

void SAMICoreAudioEncoderDestory(SAMICoreAudioEncoder audioEncoder);

作用：
销毁编码器
参数说明：

示例：

SAMICoreAudioEncoderDestory(audioEncoder);

完整示例

#include "sami_core_audio_io.h"

SAMICoreAudioEncoderSettings settings;
memset(&settings, 0, sizeof(SAMICoreAudioEncoderSettings));
settings.format = SAMICoreAudioEncoderFormat::kWav_F32;
settings.acc = SAMICoreAudioEncoderAcceleration::kSoftware;
settings.threading = SAMICoreAudioEncoderThreading::kSingleThreaded;
settings.num_threads = 0;
SAMICoreAudioEncoder audioEncoder;
ret = SAMICoreAudioEncoderCreate(&audioEncoder, &settings);
if(ret != SAMI_OK) {
    return -1;
}

const char *output_file = "/path/file";
ret = SAMICoreAudioEncoderOpen(audioEncoder, output_file, sample_rate, num_channels, bit_rate);
if(ret != SAMI_OK) {
    return -1;
}
//交织数据写入，data为float*类型
float *interleave_data = new float[num_samples * num_channels];
memset(interleave_data, 0, sizeof(float));
int write_size = SAMICoreAudioEncoderWriteInterleaveData(audioEncoder, interleave_data, num_channels, num_samples);
delete[] interleave_data;

//非交织数据写入，data为float**类型
float **planar_data = new float*[num_channels];
for(int i = 0; i < num_channels; ++i) {
    planar_data[i] = new float[num_samples];
    memset(planar_data, 0, sizeof(float));
}
int write_size = SAMICoreAudioEncoderWritePlanarData(audioEncoder, planar_data, num_channels, num_samples);
for(int i = 0; i < num_channels; ++i) {
    delete[] planar_data[i];
}
delete[] planar_data;

SAMICoreAudioEncoderClose(audioEncoder);
SAMICoreAudioEncoderDestory(audioEncoder);

MIDI读取

头文件：

#include "sami_core_audio_io.h"

接入步骤：

MIDI Event读取

1. 读取midi数据

函数名：

SAMICoreMidiEventArray SAMICoreReadMidiEventsFromFile(const char* path, 
                                                      size_t track_idx = 0);

作用：
通过传入midi文件路径获取文件中指定轨道的midi event数组
参数说明：

返回值：
文件中指定轨道的midi event数组

• SAMICoreMidiEventArray

• SAMICoreMidiEvent

示例：

SAMICoreMidiEventArray midiEventArray = SAMICoreReadMidiEventsFromFile(midi_path);

2. 销毁midi数据

函数名：

void SAMICoreMidiEventDestory(SAMICoreMidiEventArray midi_array);

作用：
销毁midi event数组
参数说明：

示例：

SAMICoreMidiEventDestory(midiEventArray);

MIDI Note读取

1. 读取midi数据

函数名：

SAMICoreMidiNoteArray SAMICoreReadMidiNotesFromFile(const char* path, 
                                                    size_t track_idx = 0,
                                                    bool truncate = true);

作用：
通过传入midi文件路径获取文件中指定轨道的midi note数组
参数说明：

返回值：
文件中指定轨道的midi note数组

• SAMICoreMidiNoteArray

• SAMICoreMidiNote

示例：

SAMICoreMidiNoteArray midiNoteArray = SAMICoreReadMidiNotesFromFile(midi_path);

2. 销毁midi数据

函数名：

void SAMICoreMidiNoteDestory(SAMICoreMidiNoteArray midi_array);

作用：
销毁midi note数组
参数说明：

示例：

SAMICoreMidiNoteArray(midiNoteArray);

完整示例

#include "sami_core_audio_io.h"

const char *midi_path = "/path/file";
SAMICoreMidiNoteArray midiNoteArray = SAMICoreReadMidiNotesFromFile(midi_path, -1);
std::cout << "midiNoteArray.length = " << midiNoteArray.length << std::endl;
for(int i = 0; i < midiNoteArray.length; ++i) {
    std::cout << "time_ms: " << midiNoteArray.notes[i].time_ms << " pitch: " << midiNoteArray.notes[i].pitch << std::endl;
}
SAMICoreMidiNoteDestory(midiNoteArray);

SAMICoreMidiEventArray midiEventArray = SAMICoreReadMidiEventsFromFile(midi_path, -1, true);
std::cout << "midiEventArray.length = " << midiEventArray.length << std::endl;
for(int i = 0; i < midiEventArray.length; ++i) {
    std::cout << "time_ms: " << midiEventArray.events[i].time_ms << " event_type: " << midiEventArray.events[i].event_type << std::endl;
}
SAMICoreMidiEventDestory(midiEventArray);

解码

引入类名：

import com.mammon.audiosdk.SAMICoreIo;

接入步骤：

1. 创建解码器

函数名：

class SAMICoreIo {
    public int FileSourceCreate(String path);
}

作用：
根据传入音频文件路径创建解码器，可通过解码器获取音频信息、读取音频数据
参数说明：

注意：

一个SAMICoreIo只能打开一个编码器和解码器，不能重复打开多个编码器/解码器

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICoreIo io = new SAMICoreIo();

int ret = io.FileSourceCreate(input_path);
if(ret != 0) {
    return;
}

2. 获取音频信息

获取采样率

函数名：

class SAMICoreIo {
    public long FileSourceGetSampleRate();
}

作用：
获取音频文件采样率，采样率概念可见名次解释
返回值：
音频文件采样率
示例：

long num_samples = io.FileSourceGetSampleRate();

获取声道数

函数名：

class SAMICoreIo {
    public long FileSourceGetNumChannel();
}

作用：
获取音频文件声道数，声道数概念可见名词解释
返回值：
音频文件声道数
示例：

long num_channel = io.FileSourceGetNumChannel();

获取位深度

函数名：

class SAMICoreIo {
    public long FileSourceGetNumBit();
}

作用：
获取音频文件位深度，位深度概念可见名次解释
返回值：
音频文件位深度
示例：

long num_bit = io.FileSourceGetNumBit();

获取采样点数

函数名：

class SAMICoreIo {
    public long FileSourceGetNumFrames();
}

作用：
获取音频文件单个通道的采样点数
返回值：
音频文件采样点数，双声道时返回单个通道的采样点数
示例：

long num_samples = io.FileSourceGetNumFrames();

获取当前读取位置

函数名：

class SAMICoreIo {
    public long FileSourceGetPosition();
}

作用：
获取当前读取的采样点位置
返回值：
解码器当前读取的采样点位置，双声道时返回一个声道的采样点位置
示例：

long position = io.FileSourceGetPosition();

3. 设置读取位置

函数名：

class SAMICoreIo {
    public boolean FileSourceSeek(long position);
}

作用：
设置后续需要读取的开始位置
参数说明：

返回值：
true成功，false失败
示例：

boolean ret = io.FileSourceSeek(position);

4. 读取音频原始数据

函数名：

class SAMICoreIo {
    public int FileSourceRead(float[] read_data, long frame_num);
}

作用：
读取音频原始数据
参数说明：

返回值：
成功读取的采样点数
示例：

float[] read_data = new float[read_size];
int read_num = io.FileSourceRead(read_data, read_size);

5. 销毁解码器

函数名：

class SAMICoreIo {
    public void FileSourceClose();
}

作用：
销毁解码器
示例：

io.FileSourceClose();

完整示例

import com.mammon.audiosdk.SAMICoreIo;

SAMICoreIo io = new SAMICoreIo();

String input_path = "/path/file";
int ret = io.FileSourceCreate(input_path);
if(ret != 0) {
    return;
}

boolean ret = io.FileSourceSeek(position);

long num_channel = io.FileSourceGetNumChannel();
long num_samples = io.FileSourceGetNumFrames();
long sample_rate = io.FileSourceGetSampleRate();

float[] read_data = new float[read_size];
int read_num = io.FileSourceRead(read_data, read_size);
io.FileSourceClose();

编码

引入类名：

import com.mammon.audiosdk.SAMICoreIo;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderAcceleration;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderFormat;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderThreading;
import com.mammon.audiosdk.structures.SAMICoreAudioEncoderSettings;

接入步骤：

1. 创建编码器

函数名：

class SAMICoreIo {
    public int AudioEncoderCreate(SAMICoreAudioEncoderSettings settings);
}

作用：
根据传入编码设置创建编码器
参数说明：

• SAMICoreAudioEncoderSettings

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICoreAudioEncoderSettings settings = new SAMICoreAudioEncoderSettings();
settings.format = SAMICoreAudioEncoderFormat.KWav_F32;
settings.acc = SAMICoreAudioEncoderAcceleration.KSoftware;
settings.threading = SAMICoreAudioEncoderThreading.KSingleThreaded;
settings.num_threads = 0;

int res = io.AudioEncoderCreate(settings);
if(res != 0) {
    return;
}

2. 打开音频文件

函数名：

class SAMICoreIo {
    public int AudioEncoderOpen(String output_path, 
                                int sample_rate, 
                                int num_channels, 
                                long bit_rate);
}

作用：
传入目标路径、采样率、声道数、码率，通过编码器打开目标音频文件
参数说明：

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

res = io.AudioEncoderOpen(output_path, sample_rate, num_channel, bit_rate);
if(res != 0) {
    return;
}

3. 获取文件信息

获取文件状态

函数名：

class SAMICoreIo {
    public boolean AudioEncoderIsOpen();
}

作用：
获取当前音频文件状态
返回值：
目标音频文件当前状态
示例：

boolean is_open = io.AudioEncoderIsOpen();

获取采样率

函数名：

class SAMICoreIo {
    public int AudioEncoderGetSampleRate();
}

作用：
获取音频文件采样率
返回值：
目标音频文件采样率
示例：

int sample_rate = io.AudioEncoderGetSampleRate();

获取声道数

函数名：

class SAMICoreIo {
    public int AudioEncoderGetNumChannels();
}

作用：
获取音频文件声道数
返回值：
目标音频文件声道数
示例：

int num_channels = io.AudioEncoderGetNumChannels();

4. 写入音频原始数据

Interleave格式写入

函数名：

class SAMICoreIo {
    public long AudioEncoderWriteInterleaveData(float[] interleave_data,
                                                int num_channels, 
                                                long num_sample_per_channel);
}

作用：
通过编码器将Interleave格式音频数据写入文件，Interleave格式可见名词解释
参数说明：

返回值：
成功写入的采样点数
示例：

long write_size = io.AudioEncoderWriteInterleaveData(interleave_data, num_channels, num_samples);

Planar格式写入

函数名：

class SAMICoreIo {
    public long AudioEncoderWritePlanarData(float[][] planar_data, 
                                            int num_channels, 
                                            long num_sample_per_channel);
}

作用：
通过编码器将planar格式音频数据写入文件，planar格式可见名次解释
参数说明：

返回值：
成功写入的采样点数
示例：

long write_size = io.AudioEncoderWritePlanarData(planar_data, num_channels, num_samples);

5. 关闭编码器

函数名：

class SAMICoreIo {
    public void AudioEncoderClose();
}

作用：
关闭编码器
示例：

io.AudioEncoderClose();

完整示例

import com.mammon.audiosdk.SAMICoreIo;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderAcceleration;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderFormat;
import com.mammon.audiosdk.enums.SAMICoreAudioEncoderThreading;
import com.mammon.audiosdk.structures.SAMICoreAudioEncoderSettings;

SAMICoreIo io = new SAMICoreIo();

SAMICoreAudioEncoderSettings settings = new SAMICoreAudioEncoderSettings();
settings.format = SAMICoreAudioEncoderFormat.KWav_F32;
settings.acc = SAMICoreAudioEncoderAcceleration.KSoftware;
settings.threading = SAMICoreAudioEncoderThreading.KSingleThreaded;
settings.num_threads = 0;

int res = io.AudioEncoderCreate(settings);
if(res != 0) {
    return;
}

String output_path = "/path/file";
res = io.AudioEncoderOpen(output_path, sample_rate, num_channel, bit_rate);
if(res != 0) {
    return;
}
//交织数据写入
long write_num = io.AudioEncoderWriteInterleaveData(interleave_data, num_channel, write_size);

//非交织数据写入
long write_num = io.AudioEncoderWritePlanarData(planner_data, num_channel, write_size);

io.AudioEncoderClose();

MIDI读取

引入类名：

import com.mammon.audiosdk.SAMICoreIo;
import com.mammon.audiosdk.structures.SAMICoreMidiNote;
import com.mammon.audiosdk.structures.SAMICoreMidiEvent;

接入步骤：

MIDI Event读取

函数名：

class SAMICoreIo {
    public SAMICoreMidiEvent[] readMidiEventsFromFile(String path, int track_idx);
}

作用：
通过传入midi文件路径获取文件中指定轨道的midi event数组
参数说明：

返回值：
文件中指定轨道的midi event数组

• SAMICoreMidiEvent

示例：

SAMICoreMidiEvent[] events = io.readMidiEventsFromFile(midi_path, -1);

MIDI Note读取

函数名：

class SAMICoreIo {
    public SAMICoreMidiNote[] readMidiNotesFromFile(String path, 
                                                    int track_idx, 
                                                    boolean truncate);
}

作用：
通过传入midi文件路径获取文件中指定轨道的midi note数组
参数说明：

返回值：
文件中指定轨道的midi note数组

• SAMICoreMidiNote

示例：

SAMICoreMidiNote[] notes =  io.readMidiNotesFromFile(midi_path, -1, true);

完整示例

import com.mammon.audiosdk.SAMICoreIo;
import com.mammon.audiosdk.structures.SAMICoreMidiNote;
import com.mammon.audiosdk.structures.SAMICoreMidiEvent;

SAMICoreIo io = new SAMICoreIo();//只需要初始化一次

String midi_path = "/path/file";
SAMICoreMidiEvent[] events = io.readMidiEventsFromFile(midi_path, -1);
SAMICoreMidiNote[] notes =  io.readMidiNotesFromFile(midi_path, 0, true);

解码

头文件：

#import "SAMICoreFileSource.h"

接入步骤：

1. 创建解码器

函数名：

@interface SAMICore_FileSource: NSObject
- (_Nullable id)create:(NSString* _Nonnull)path;
@end

作用：
根据传入音频文件路径创建解码器，可通过解码器获取音频信息、读取音频数据
参数说明：

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICore_FileSource *file_src = [[SAMICore_FileSource alloc] create:input_file];
if(!file_src) {
    NSLog(@"create File Source fail!");
    return;
}

2. 获取音频信息

获取采样率

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)getSampleRate;
@end

作用：
获取音频文件采样率，采样率概念可见名词解释
返回值：
音频文件采样率
示例：

size_t sample_rate = [file_src getSampleRate];

获取声道数

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)getNumChannel;
@end

作用：
获取音频文件声道数，声道数概念可见名词解释
返回值：
音频文件声道数
示例：

size_t num_channel = [file_src getNumChannel];

获取位深度

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)getNumBit;
@end

作用：
获取音频文件位深度，位深度概念可见名词解释
返回值：
音频文件位深度
示例：

size_t num_bit = [file_src getNumBit];

获取采样点数

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)getNumFrames;
@end

作用：
获取音频文件单个通道的采样点数
返回值：
音频文件采样点数，双声道时返回单个通道的采样点数
示例：

size_t num_samples = [file_src getNumFrames];

获取当前读取位置

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)getPosition;
@end

作用：
获取当前读取的采样点位置
返回值：
解码器当前读取的采样点位置，双声道时返回一个声道的采样点位置
示例：

size_t position = [file_src getPosition];

3. 设置读取位置

函数名：

@interface SAMICore_FileSource: NSObject
- (bool)seek:(size_t)position;
@end

作用：
设置后续需要读取的开始位置
参数说明：

返回值：
true成功，false失败
示例：

bool ret = [file_src seek:position];

4. 读取音频原始数据

函数名：

@interface SAMICore_FileSource: NSObject
- (size_t)readWithData:(float* _Nonnull)interleave_buffer NumFrame:(size_t)frame_num;
@end

作用：
读取音频原始数据
参数说明：

返回值：
实际读取的采样点数，双声道时返回实际单声道采样点数
示例：

float interleave_buffer[need_alloc_memory];
size_t read_samples = [file_src readWithData:reinterpret_cast<float *>(&interleave_buffer) NumFrame:num_samples];

5. 销毁解码器

函数名：

@interface SAMICore_FileSource: NSObject
- (void)close;
@end

作用：
销毁解码器
示例：

[file_src close];

完整示例

#import "SAMICoreFileSource.h"

NSString* input_file = @"/path/file";
SAMICore_FileSource *file_src = [[SAMICore_FileSource alloc] create:input_file];
if(!file_src) {
    NSLog(@"create File Source fail!");
    return;
}

bool ret = [file_src seek:position];

size_t num_samples = [file_src getNumFrames];
size_t sample_rate = [file_src getSampleRate];
size_t num_channel = [file_src getNumChannel];

float interleave_buffer[num_samples];
size_t read_samples = [file_src readWithData:reinterpret_cast<float *>(&interleave_buffer) NumFrame:num_samples];
[file_src close];

编码

头文件：

#import "SAMICoreAudioEncoder.h"

接入步骤：

1. 创建编码器

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (_Nullable id)createWithAudioEncoderSettings:(SAMICore_AudioEncoderSettings* _Nonnull)settings;
@end

作用：
根据传入编码设置创建编码器
参数说明：

• SAMICore_AudioEncoderSettings

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

SAMICore_AudioEncoderSettings *settings = [[SAMICore_AudioEncoderSettings alloc] initWithAudioEncoderFormat:SAMICore_AudioEncoderFormat::kWav_F32
                                                                AudioEncoderAcceleration:SAMICore_AudioEncoderAcceleration::kSoftware
                                                                   AudioEncoderThreading:SAMICore_AudioEncoderThreading::kSingleThreaded
                                                                              NumThreads:0];
SAMICore_AudioEncoder *audio_encoder = [[SAMICore_AudioEncoder alloc] createWithAudioEncoderSettings:settings];
if(!audio_encoder) {
    NSLog(@"create Audio Encoder fail!");
    return;
}

2. 打开音频文件

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (int)openWithOutputPath:(NSString* _Nonnull)output_path
               SampleRate:(int)sample_rate
               NumChannels:(int)num_channels
                   BitRate:(int)bit_rate;
@end

作用：
传入目标路径、采样率、声道数、码率，通过编码器打开目标音频文件
参数说明：

返回值：
0 成功，非 0 失败，具体错误码参考sami_core_error_code.h
示例：

int ret = [audio_encoder openWithOutputPath:output_file
           SampleRate:sample_rate
           NumChannels:num_channel
               BitRate:bit_rate];
if(ret != 0) {
    NSLog(@"open output file fail!");
    return;
}

3. 获取文件信息

获取文件状态

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (bool)isOpen;
@end

作用：
获取当前音频文件状态
返回值：
目标音频文件当前状态
示例：

bool is_open = [audio_encoder isOpen];

获取采样率

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (int)getSampleRate;
@end

作用：
获取音频文件采样率
返回值：
目标音频文件采样率
示例：

int sample_rate = [audio_encoder getSampleRate];

获取声道数

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (int)getNumChannels;
@end

作用：
获取音频文件声道数
返回值：
目标音频文件声道数
示例：

int num_channels = [audio_encoder getNumChannels];

4. 写入音频原始数据

Interleave格式写入

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (int64_t) writeInterleaveData:(void* _Nonnull)interleave_data
                     NumChannels:(int)num_channels
             NumSamplePerChannel:(int64_t)num_sample_per_channel;
@end

作用：
通过编码器将Interleave格式音频数据写入文件，Interleave格式可见名词解释
参数说明：

返回值：
成功写入的采样点数
示例：

int write_size = [audio_encoder writeInterleaveData:samples_data
                       NumChannels:num_channel
               NumSamplePerChannel:num_samples];

Planar格式写入

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (int64_t) writePlanarData:(void* _Nonnull) planar_data
                  NumChannels:(int)num_channels
          NumSamplePerChannel:(int64_t)num_sample_per_channel;
@end

作用：
通过编码器将planar格式音频数据写入文件，planar格式可见名词解释
参数说明：

返回值：
成功写入的采样点数
示例：

int write_size = [audio_encoder writePlanarData:samples_data
                       NumChannels:num_channel
               NumSamplePerChannel:num_samples];

5. 关闭编码器

函数名：

@interface SAMICore_AudioEncoder: NSObject
- (void)close;
@end

作用：
关闭编码器
示例：

[audio_encoder close];

完整示例

#import "SAMICoreAudioEncoder.h"

SAMICore_AudioEncoderSettings *settings = [[SAMICore_AudioEncoderSettings alloc] initWithAudioEncoderFormat:SAMICore_AudioEncoderFormat::kWav_F32
                                                                AudioEncoderAcceleration:SAMICore_AudioEncoderAcceleration::kSoftware
                                                                   AudioEncoderThreading:SAMICore_AudioEncoderThreading::kSingleThreaded
                                                                              NumThreads:0];
SAMICore_AudioEncoder *audio_encoder = [[SAMICore_AudioEncoder alloc] createWithAudioEncoderSettings:settings];
if(!audio_encoder) {
    NSLog(@"create Audio Encoder fail!");
    return;
}

NSString *output_file = @"/path/file";
int ret = [audio_encoder openWithOutputPath:output_file
           SampleRate:sample_rate
           NumChannels:num_channel
               BitRate:bit_rate];
if(ret != 0) {
    NSLog(@"open output file fail!");
    return;
}

//交织数据写入
float* samples_data = new float[num_samples * num_channel];
[audio_encoder writeInterleaveData:samples_data
                       NumChannels:num_channel
               NumSamplePerChannel:num_samples];
delete[] samples_data;
               
//非交织数据写入
float** samples_data = new float*[num_channel];
for(int i = 0; i < num_channel; ++i) {
    samples_data[i] = new float[num_samples];
}
[audio_encoder writePlanarData:samples_data
                       NumChannels:num_channel
               NumSamplePerChannel:num_samples];
for(int i = 0; i < num_channel; ++i) {
    delete[] samples_data[i];
}
delete[] samples_data;
               
[audio_encoder close];

MIDI读取

头文件：

#import "SAMICoreMidiReader.h"

接入步骤：

MIDI Event读取

函数名：

@interface SAMICore_MidiReader: NSObject
+ (NSArray<SAMICore_MidiEvent*>* _Nonnull)readMidiEventsFromFile:(NSString * _Nonnull)path
                                          TrackIndex:(size_t)track_idx;
@end

作用：
通过传入midi文件路径获取文件中指定轨道的midi event数组
参数说明：

返回值：
文件中指定轨道的midi event数组

• SAMICore_MidiEvent

示例：

NSArray<SAMICore_MidiEvent *>* midi_events = [SAMICore_MidiReader readMidiEventsFromFile:midi_file
                                                                 TrackIndex:0];

MIDI Note读取

函数名：

@interface SAMICore_MidiReader: NSObject
+ (NSArray<SAMICore_MidiNote*>* _Nonnull)readMidiNotesFromFile:(NSString * _Nonnull)path
                                        TrackIndex:(size_t)track_idx
                                          Truncate:(bool)truncate;
@end

作用：
通过传入midi文件路径获取文件中指定轨道的midi note数组
参数说明：

返回值：
文件中指定轨道的midi note数组

• SAMICore_MidiNote

示例：

NSArray<SAMICore_MidiNote *>* midi_notes = [SAMICore_MidiReader readMidiNotesFromFile:midi_file
                                                                 TrackIndex:0
                                                                   Truncate:true];

完整示例

#import "SAMICoreMidiReader.h"

NSString *midi_file = @"path/file";
NSArray<SAMICore_MidiEvent *>* midi_events = [SAMICore_MidiReader readMidiEventsFromFile:midi_file
                                                                 TrackIndex:0];
NSArray<SAMICore_MidiNote *>* midi_notes = [SAMICore_MidiReader readMidiNotesFromFile:midi_file
                                                                 TrackIndex:0
                                                                   Truncate:true];

信息

接入必读：

• SDK快速入门：https://www.volcengine.com/docs/6489/171423

材料

SDK和demo等资源见：https://www.volcengine.com/docs/6489/72021