Add example for usage from C/C++

Author: Daninet

Cargo.toml

@@ -18,7 +18,7 @@ hound = "3.5.1"
 clap = "4.5.30"
 
 [lib]
-crate-type = ["cdylib", "rlib"]
+crate-type = ["cdylib", "staticlib", "rlib"]
 
 [features]
 default = ["wasm-api"]

README.md

@@ -48,6 +48,11 @@ Options:
           Print help
 ```
 
+### C API
+
+A C API is available for integrating SEA into C/C++ projects.
+See the [C API README](examples/c_api/README.md) for usage details and build instructions.
+
 # SEA file specification
 
 A SEA file consists of a file header followed by a series of chunks. Samples are stored as 16-bit signed integers in interleaved format. All values are stored in little-endian order.

examples/c_api/.gitignore

@@ -0,0 +1 @@
+build

examples/c_api/CMakeLists.txt

@@ -0,0 +1,31 @@
+cmake_minimum_required(VERSION 3.10)
+project(sea_codec_c_example)
+
+set(CMAKE_C_STANDARD 99)
+
+# Include directories
+include_directories(../../include)
+
+# Find the library
+if(CMAKE_BUILD_TYPE STREQUAL "Release")
+    set(LIB_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../target/release")
+else()
+    set(LIB_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../target/debug")
+endif()
+
+message(STATUS "Looking for library in ${LIB_DIR}")
+
+find_library(SEA_LIB NAMES sea_codec libsea_codec sea_codec.dll PATHS ${LIB_DIR} NO_DEFAULT_PATH)
+
+if(NOT SEA_LIB)
+    message(WARNING "sea-codec library not found in ${LIB_DIR}. Please build the rust project first (cargo build).")
+endif()
+
+add_executable(c_example main.c)
+
+if(SEA_LIB)
+    target_link_libraries(c_example ${SEA_LIB})
+    if(UNIX) 
+        target_link_libraries(c_example m pthread dl) 
+    endif()
+endif()

examples/c_api/README.md

@@ -0,0 +1,62 @@
+# C API Example for sea-codec
+
+This directory contains an example of how to use the C API of `sea-codec` from a C application.
+
+## Prerequisites
+
+- Rust (cargo)
+- CMake
+- A C compiler (GCC, Clang, MSVC)
+
+## Structure
+
+- `main.c`: A simple C program that generates a sine wave, encodes it using `sea-codec`, and decodes it back.
+- `CMakeLists.txt`: A CMake build file demonstrating how to link against the `sea-codec` library.
+
+## Building and Running
+
+1. **Build the Rust library:**
+
+   From the root of the repository:
+
+   ```bash
+   cargo build --release
+   ```
+
+   This will generate the static and dynamic libraries in `target/release`.
+
+2. **Build the C example:**
+
+   ```bash
+   cd examples/c_api
+   mkdir build
+   cd build
+   cmake -DCMAKE_BUILD_TYPE=Release ..
+   cmake --build .
+   ```
+
+3. **Run the example:**
+
+   On Linux/macOS:
+   ```bash
+   ./c_example
+   ```
+
+   On Windows:
+   ```bash
+   .\Release\c_example.exe
+   ```
+   (Note: If linking dynamically, ensure `sea_codec.dll` is in the same directory or in PATH).
+
+## Header File
+
+The C header file is located at `include/sea_codec.h`. You should include this in your C/C++ projects.
+
+## Cross-compilation
+
+To build a static library for a different platform (e.g., ARM Cortex-M3), use `rustup` to add the target and `cargo` to build:
+
+```sh
+rustup target add thumbv7m-none-eabi
+cargo build --release --target thumbv7m-none-eabi
+```

examples/c_api/main.c

@@ -0,0 +1,77 @@
+#include "../../include/sea_codec.h"
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#ifndef M_PI
+#define M_PI 3.14159265358979323846
+#endif
+
+void generate_sine_wave(int16_t* buffer, size_t length, uint32_t sample_rate, float frequency)
+{
+    for (size_t i = 0; i < length; i++) {
+        float t = (float)i / sample_rate;
+        buffer[i] = (int16_t)(sinf(2.0f * (float)M_PI * frequency * t) * 32000.0f);
+    }
+}
+
+int main()
+{
+    uint32_t sample_rate = 44100;
+    uint32_t channels = 1;
+    float duration = 1.0f;
+    size_t num_samples = (size_t)(sample_rate * duration);
+
+    printf("Generating %zu samples of sine wave...\n", num_samples);
+    int16_t* input_samples = (int16_t*)malloc(num_samples * sizeof(int16_t));
+    if (!input_samples) {
+        fprintf(stderr, "Memory allocation failed\n");
+        return 1;
+    }
+
+    generate_sine_wave(input_samples, num_samples, sample_rate, 440.0f);
+
+    printf("Encoding...\n");
+    CSeaEncoderSettings settings = sea_encoder_default_settings();
+    uint8_t* encoded_data = NULL;
+    size_t encoded_length = 0;
+
+    int result = sea_encode(input_samples, num_samples, sample_rate, channels, &settings, &encoded_data, &encoded_length);
+
+    if (result != 0) {
+        fprintf(stderr, "Encoding failed\n");
+        free(input_samples);
+        return 1;
+    }
+
+    printf("Encoded size: %zu bytes\n", encoded_length);
+
+    printf("Decoding...\n");
+    int16_t* decoded_samples = NULL;
+    size_t decoded_sample_count = 0;
+    uint32_t decoded_sample_rate = 0;
+    uint32_t decoded_channels = 0;
+
+    result = sea_decode(encoded_data, encoded_length, &decoded_samples, &decoded_sample_count, &decoded_sample_rate, &decoded_channels);
+
+    if (result != 0) {
+        fprintf(stderr, "Decoding failed\n");
+        sea_free_packet(encoded_data, encoded_length);
+        free(input_samples);
+        return 1;
+    }
+
+    printf("Decoded info: %zu samples, %u Hz, %u channels\n", decoded_sample_count, decoded_sample_rate, decoded_channels);
+
+    if (decoded_sample_count == num_samples) {
+        printf("Sample count matches!\n");
+    } else {
+        printf("Sample count mismatch! Expected %zu, got %zu\n", num_samples, decoded_sample_count);
+    }
+
+    sea_free_packet(encoded_data, encoded_length);
+    sea_free_samples(decoded_samples, decoded_sample_count);
+    free(input_samples);
+
+    return 0;
+}

include/sea_codec.h

@@ -0,0 +1,57 @@
+#ifndef SEA_CODEC_H
+#define SEA_CODEC_H
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    uint8_t scale_factor_bits;
+    uint8_t scale_factor_frames;
+    float residual_bits;
+    uint16_t frames_per_chunk;
+    bool vbr;
+} CSeaEncoderSettings;
+
+// Helper to get default settings
+CSeaEncoderSettings sea_encoder_default_settings();
+
+// Encode
+// Returns 0 on success, non-zero on error.
+// output_data is allocated by the function and must be freed by sea_free_packet.
+// input_length is the number of samples (total, across all channels)
+int sea_encode(
+    const int16_t* input_samples,
+    size_t input_length, 
+    uint32_t sample_rate,
+    uint32_t channels,
+    const CSeaEncoderSettings* settings,
+    uint8_t** output_data,
+    size_t* output_length
+);
+
+// Decode
+// output_samples is allocated by the function and must be freed by sea_free_samples.
+int sea_decode(
+    const uint8_t* encoded_data,
+    size_t encoded_length,
+    int16_t** output_samples,
+    size_t* output_sample_count,
+    uint32_t* output_sample_rate,
+    uint32_t* output_channels
+);
+
+// Memory management
+// length must match the size returned by the allocate functions
+void sea_free_packet(uint8_t* data, size_t length);
+void sea_free_samples(int16_t* samples, size_t length);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // SEA_CODEC_H

src/c_api.rs

@@ -0,0 +1,123 @@
+use crate::{
+    encoder::EncoderSettings, sea_decode as rust_sea_decode, sea_encode as rust_sea_encode,
+};
+use alloc::vec::Vec;
+use core::ffi::c_float;
+use core::slice;
+
+#[repr(C)]
+pub struct CSeaEncoderSettings {
+    pub scale_factor_bits: u8,
+    pub scale_factor_frames: u8,
+    pub residual_bits: c_float,
+    pub frames_per_chunk: u16,
+    pub vbr: bool,
+}
+
+impl From<&CSeaEncoderSettings> for EncoderSettings {
+    fn from(c_settings: &CSeaEncoderSettings) -> Self {
+        Self {
+            scale_factor_bits: c_settings.scale_factor_bits,
+            scale_factor_frames: c_settings.scale_factor_frames,
+            residual_bits: c_settings.residual_bits,
+            frames_per_chunk: c_settings.frames_per_chunk,
+            vbr: c_settings.vbr,
+        }
+    }
+}
+
+#[no_mangle]
+pub extern "C" fn sea_encoder_default_settings() -> CSeaEncoderSettings {
+    let default = EncoderSettings::default();
+    CSeaEncoderSettings {
+        scale_factor_bits: default.scale_factor_bits,
+        scale_factor_frames: default.scale_factor_frames,
+        residual_bits: default.residual_bits,
+        frames_per_chunk: default.frames_per_chunk,
+        vbr: default.vbr,
+    }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn sea_encode(
+    input_samples: *const i16,
+    input_length: usize,
+    sample_rate: u32,
+    channels: u32,
+    settings: *const CSeaEncoderSettings,
+    output_data: *mut *mut u8,
+    output_length: *mut usize,
+) -> i32 {
+    if input_samples.is_null() || output_data.is_null() || output_length.is_null() {
+        return -1;
+    }
+
+    let input_slice = slice::from_raw_parts(input_samples, input_length);
+    let encoder_settings = if settings.is_null() {
+        EncoderSettings::default()
+    } else {
+        EncoderSettings::from(&*settings)
+    };
+
+    let mut encoded = rust_sea_encode(input_slice, sample_rate, channels, encoder_settings);
+
+    encoded.shrink_to_fit();
+    let ptr = encoded.as_mut_ptr();
+    let len = encoded.len();
+    core::mem::forget(encoded);
+
+    *output_data = ptr;
+    *output_length = len;
+
+    0
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn sea_decode(
+    encoded_data: *const u8,
+    encoded_length: usize,
+    output_samples: *mut *mut i16,
+    output_sample_count: *mut usize,
+    output_sample_rate: *mut u32,
+    output_channels: *mut u32,
+) -> i32 {
+    if encoded_data.is_null() || output_samples.is_null() || output_sample_count.is_null() {
+        return -1;
+    }
+
+    let encoded_slice = slice::from_raw_parts(encoded_data, encoded_length);
+
+    let decode_info = rust_sea_decode(encoded_slice);
+
+    let mut samples = decode_info.samples;
+    samples.shrink_to_fit();
+    let ptr = samples.as_mut_ptr();
+    let len = samples.len();
+    core::mem::forget(samples);
+
+    *output_samples = ptr;
+    *output_sample_count = len;
+
+    if !output_sample_rate.is_null() {
+        *output_sample_rate = decode_info.sample_rate;
+    }
+    if !output_channels.is_null() {
+        *output_channels = decode_info.channels;
+    }
+
+    0
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn sea_free_packet(data: *mut u8, length: usize) {
+    if !data.is_null() {
+        let _ = Vec::from_raw_parts(data, length, length);
+    }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn sea_free_samples(samples: *mut i16, length: usize) {
+    if !samples.is_null() {
+        let _ = Vec::from_raw_parts(samples, length, length);
+    }
+}

src/lib.rs

@@ -13,6 +13,8 @@ pub mod encoder;
 #[cfg(all(target_arch = "wasm32", feature = "wasm-api"))]
 pub mod wasm_api;
 
+pub mod c_api;
+
 pub fn sea_encode(
     input_samples: &[i16],
     sample_rate: u32,