Merge pull request #4 from hTuneSys/main

sync: main → develop (v0.1.2)

Author: husamettinarabaci

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "hexatune-dsp-ffi"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2024"
 license = "MIT"
 authors = ["hexaTune LLC"]

Cargo.toml

@@ -171,9 +171,15 @@ A single step in the frequency cycle.
 typedef struct HtdCycleItem {
     float frequency_delta;    // Hz delta added to carrier
     float duration_seconds;   // How long this step lasts
+    bool oneshot;             // If true, plays only in the first cycle iteration
 } HtdCycleItem;
 ```
 
+**One-shot items:** When `oneshot` is `true`, the item plays during the first
+pass through the cycle and is skipped on all subsequent iterations. If every
+item in the cycle is one-shot, the binaural/tone layer goes silent after the
+first pass while ambience layers continue playing.
+
 #### `HtdEngineConfig`
 
 Configuration for engine initialization.
@@ -256,12 +262,21 @@ int32_t htd_engine_start(HtdEngine *engine);  // Returns 0 on success
 
 #### `htd_engine_stop`
 
-Stop audio generation. Render will output silence.
+Stop audio generation immediately. Render will output silence.
 
 ```c
 int32_t htd_engine_stop(HtdEngine *engine);  // Returns 0 on success
 ```
 
+#### `htd_engine_stop_graceful`
+
+Request a graceful stop. The engine finishes playing all remaining items in the
+current cycle iteration, then automatically stops (including all layers).
+
+```c
+int32_t htd_engine_stop_graceful(HtdEngine *engine);  // Returns 0 on success
+```
+
 #### `htd_engine_is_running`
 
 Query engine state.
@@ -430,13 +445,16 @@ void startSoundscape() {
   final cycleItems = calloc<HtdCycleItem>(3);
   cycleItems[0]
     ..frequency_delta = 3.0
-    ..duration_seconds = 30.0;
+    ..duration_seconds = 30.0
+    ..oneshot = false;
   cycleItems[1]
     ..frequency_delta = 4.0
-    ..duration_seconds = 30.0;
+    ..duration_seconds = 30.0
+    ..oneshot = true;   // plays only in the first cycle pass
   cycleItems[2]
     ..frequency_delta = 5.0
-    ..duration_seconds = 30.0;
+    ..duration_seconds = 30.0
+    ..oneshot = false;
 
   // 2. Build config
   final config = calloc<HtdEngineConfig>();
@@ -524,11 +542,11 @@ void audioCallback(Pointer<Float> buffer, int numFrames) {
 #include <stdio.h>
 
 int main(void) {
-    // Frequency cycle: 3Hz->4Hz->5Hz, 30s each
+    // Frequency cycle: 3Hz->4Hz->5Hz, 30s each; 4Hz is one-shot
     HtdCycleItem cycle[] = {
-        { .frequency_delta = 3.0f, .duration_seconds = 30.0f },
-        { .frequency_delta = 4.0f, .duration_seconds = 30.0f },
-        { .frequency_delta = 5.0f, .duration_seconds = 30.0f },
+        { .frequency_delta = 3.0f, .duration_seconds = 30.0f, .oneshot = false },
+        { .frequency_delta = 4.0f, .duration_seconds = 30.0f, .oneshot = true  },
+        { .frequency_delta = 5.0f, .duration_seconds = 30.0f, .oneshot = false },
     };
 
     // Engine configuration
@@ -587,8 +605,10 @@ int main(void) {
     htd_engine_set_base_gain(engine, 0.7f);
     htd_engine_set_binaural_gain(engine, 0.2f);
 
-    // Cleanup
-    htd_engine_stop(engine);
+    // Cleanup — use stop_graceful to finish the current cycle first,
+    // or stop for an immediate halt.
+    htd_engine_stop_graceful(engine);  // finishes current cycle, then stops
+    // htd_engine_stop(engine);        // alternative: immediate stop
     htd_engine_clear_all_layers(engine);
     htd_engine_destroy(engine);
     return 0;

README.md

@@ -82,6 +82,10 @@ typedef struct Engine HtdEngine;
 typedef struct HtdCycleItem {
   float frequency_delta;
   float duration_seconds;
+  /**
+   * If true, this item plays only in the first cycle iteration.
+   */
+  bool oneshot;
 } HtdCycleItem;
 
 /**
@@ -216,6 +220,19 @@ int32_t htd_engine_start(HtdEngine *engine);
  */
 int32_t htd_engine_stop(HtdEngine *engine);
 
+/**
+ * Request a graceful stop: the engine finishes the current cycle iteration
+ * (all remaining items in this pass) and then automatically stops.
+ *
+ * Ambience, texture, and event layers will also go silent once the cycle
+ * completes.
+ *
+ * # Safety
+ *
+ * `engine` must be a valid engine pointer.
+ */
+int32_t htd_engine_stop_graceful(HtdEngine *engine);
+
 /**
  * Render `num_frames` of interleaved stereo f32 audio into `output`.
  *

include/hexatune_dsp_ffi.h

@@ -17,7 +17,7 @@ use crate::mixer::{
     DEFAULT_TEXTURE_GAIN, LayerGains, Mixer,
 };
 use crate::sample_player::SamplePlayer;
-use crate::scheduler::{CycleItem, Scheduler};
+use crate::scheduler::{AdvanceResult, CycleItem, Scheduler};
 
 /// Default sample rate for mobile audio.
 pub const DEFAULT_SAMPLE_RATE: f32 = 48000.0;
@@ -55,6 +55,8 @@ pub struct Engine {
     scheduler: Scheduler,
     mixer: Mixer,
     sample_rate: f32,
+    /// Set when all cycle items are exhausted (all oneshot, past first iter).
+    binaural_muted: bool,
 
     // -- Atomic shared parameters (written by control, read by audio) --
     base_gain: AtomicU32,
@@ -63,6 +65,8 @@ pub struct Engine {
     binaural_gain: AtomicU32,
     master_gain: AtomicU32,
     running: AtomicBool,
+    /// Atomic flag for graceful stop request from control thread.
+    graceful_stop_requested: AtomicBool,
 
     // -- Pending configuration (written by control, consumed by audio) --
     pending_config: Mutex<Option<PendingConfig>>,
@@ -95,14 +99,17 @@ impl Default for EngineConfig {
                 CycleItem {
                     frequency_delta: 3.0,
                     duration_seconds: 30.0,
+                    oneshot: false,
                 },
                 CycleItem {
                     frequency_delta: 4.0,
                     duration_seconds: 30.0,
+                    oneshot: false,
                 },
                 CycleItem {
                     frequency_delta: 5.0,
                     duration_seconds: 30.0,
+                    oneshot: false,
                 },
             ],
             sample_rate: DEFAULT_SAMPLE_RATE,
@@ -152,12 +159,14 @@ impl Engine {
             scheduler,
             mixer,
             sample_rate: config.sample_rate,
+            binaural_muted: false,
             base_gain: AtomicU32::new(config.base_gain.to_bits()),
             texture_gain: AtomicU32::new(config.texture_gain.to_bits()),
             event_gain: AtomicU32::new(config.event_gain.to_bits()),
             binaural_gain: AtomicU32::new(config.binaural_gain.to_bits()),
             master_gain: AtomicU32::new(config.master_gain.to_bits()),
             running: AtomicBool::new(false),
+            graceful_stop_requested: AtomicBool::new(false),
             pending_config: Mutex::new(None),
         })
     }
@@ -166,14 +175,24 @@ impl Engine {
 
     /// Mark the engine as running. Audio will be generated in [`render`].
     pub fn start(&self) {
+        self.graceful_stop_requested.store(false, Ordering::Release);
         self.running.store(true, Ordering::Release);
     }
 
     /// Mark the engine as stopped. [`render`] will output silence.
     pub fn stop(&self) {
+        self.graceful_stop_requested.store(false, Ordering::Release);
         self.running.store(false, Ordering::Release);
     }
 
+    /// Request a graceful stop: the engine continues playing until the
+    /// current cycle iteration completes, then stops automatically.
+    /// The scheduler's `stop_at_cycle_end` flag is set via an atomic bool
+    /// and applied on the next render call.
+    pub fn stop_graceful(&self) {
+        self.graceful_stop_requested.store(true, Ordering::Release);
+    }
+
     /// Whether the engine is currently running.
     pub fn is_running(&self) -> bool {
         self.running.load(Ordering::Acquire)
@@ -349,14 +368,43 @@ impl Engine {
         }
 
         for i in 0..num_frames {
-            // 1. Frequency scheduler update
-            if self.scheduler.advance() {
-                let new_delta = self.scheduler.current_delta();
-                self.binaural.set_delta(new_delta);
+            // 1. Apply graceful stop flag from control thread
+            if self
+                .graceful_stop_requested
+                .compare_exchange(true, false, Ordering::Acquire, Ordering::Relaxed)
+                .is_ok()
+            {
+                self.scheduler.set_stop_at_cycle_end(true);
+            }
+
+            // 2. Frequency scheduler update
+            match self.scheduler.advance() {
+                AdvanceResult::ItemChanged => {
+                    let new_delta = self.scheduler.current_delta();
+                    self.binaural.set_delta(new_delta);
+                }
+                AdvanceResult::AllExhausted => {
+                    self.binaural_muted = true;
+                }
+                AdvanceResult::CycleCompleteStop => {
+                    self.running.store(false, Ordering::Release);
+                    // Fill remaining frames with silence and return
+                    for j in i..num_frames {
+                        let idx = j * 2;
+                        output[idx] = 0.0;
+                        output[idx + 1] = 0.0;
+                    }
+                    return;
+                }
+                AdvanceResult::NoChange => {}
             }
 
-            // 2. Generate binaural/AM tone
-            let tone = self.binaural.generate();
+            // 3. Generate binaural/AM tone (silent if exhausted)
+            let tone = if self.binaural_muted {
+                StereoSample::default()
+            } else {
+                self.binaural.generate()
+            };
 
             // 3. Base layer
             let base = match self.base_layer.as_mut() {
@@ -405,6 +453,7 @@ impl Engine {
             }
             if let Some(items) = config.cycle_items {
                 self.scheduler.set_items(items);
+                self.binaural_muted = false;
                 let new_delta = self.scheduler.current_delta();
                 self.binaural.set_delta(new_delta);
             }
@@ -445,10 +494,12 @@ mod tests {
                 CycleItem {
                     frequency_delta: 3.0,
                     duration_seconds: 0.01,
+                    oneshot: false,
                 },
                 CycleItem {
                     frequency_delta: 5.0,
                     duration_seconds: 0.01,
+                    oneshot: false,
                 },
             ],
             sample_rate: 48000.0,

src/engine.rs

@@ -69,9 +69,7 @@ impl EventSystem {
         pan_max: f32,
     ) -> Result<(), String> {
         if index >= MAX_EVENT_SLOTS {
-            return Err(format!(
-                "event index {index} exceeds max {MAX_EVENT_SLOTS}"
-            ));
+            return Err(format!("event index {index} exceeds max {MAX_EVENT_SLOTS}"));
         }
         if samples.is_empty() {
             return Err("event samples are empty".to_string());

src/event_player.rs

@@ -42,6 +42,8 @@ pub type HtdEngine = Engine;
 pub struct HtdCycleItem {
     pub frequency_delta: f32,
     pub duration_seconds: f32,
+    /// If true, this item plays only in the first cycle iteration.
+    pub oneshot: bool,
 }
 
 /// Engine configuration passed from Flutter.
@@ -138,6 +140,7 @@ unsafe fn ffi_config_to_rust(config: *const HtdEngineConfig) -> Result<EngineCon
             .map(|item| CycleItem {
                 frequency_delta: item.frequency_delta,
                 duration_seconds: item.duration_seconds,
+                oneshot: item.oneshot,
             })
             .collect()
     };
@@ -273,6 +276,24 @@ pub unsafe extern "C" fn htd_engine_stop(engine: *mut HtdEngine) -> i32 {
     HtdError::Ok as i32
 }
 
+/// Request a graceful stop: the engine finishes the current cycle iteration
+/// (all remaining items in this pass) and then automatically stops.
+///
+/// Ambience, texture, and event layers will also go silent once the cycle
+/// completes.
+///
+/// # Safety
+///
+/// `engine` must be a valid engine pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn htd_engine_stop_graceful(engine: *mut HtdEngine) -> i32 {
+    if engine.is_null() {
+        return HtdError::NullPointer as i32;
+    }
+    unsafe { &*engine }.stop_graceful();
+    HtdError::Ok as i32
+}
+
 // ---------------------------------------------------------------------------
 // FFI functions — Render
 // ---------------------------------------------------------------------------
@@ -603,6 +624,7 @@ pub unsafe extern "C" fn htd_engine_update_config(
                 .map(|item| CycleItem {
                     frequency_delta: item.frequency_delta,
                     duration_seconds: item.duration_seconds,
+                    oneshot: item.oneshot,
                 })
                 .collect(),
         )