Lifecycle

src/engine.cpp

@@ -6,6 +6,7 @@
 #include <algorithm>
 #include <atomic>
 #include <cmath>
+#include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <expected>
@@ -17,6 +18,7 @@
 #include <string_view>
 #include <unordered_map>
 #include <utility>
+#include <vector>
 
 #include <modulus.hpp>
 
@@ -52,9 +54,38 @@ auto valid_frequency(std::float32_t value) -> std::bool_t {
   return std::isfinite(value) && value >= 20.0F && value <= 20000.0F;
 }
 
+auto contains_null(std::string_view value) -> std::bool_t {
+  return value.find('\0') != std::string_view::npos;
+}
+
+auto to_miniaudio_profile(sonus::performance_profile profile) -> ma_performance_profile {
+  switch (profile) {
+    case sonus::performance_profile::LOW_LATENCY:
+      return ma_performance_profile_low_latency;
+    case sonus::performance_profile::CONSERVATIVE:
+      return ma_performance_profile_conservative;
+  }
+  return ma_performance_profile_low_latency;
+}
+
+auto make_click_samples(std::uint32_t sample_rate, std::uint32_t frame_count, std::float32_t frequency, std::float32_t gain) -> std::vector<std::float32_t> {
+  auto result = std::vector<std::float32_t>(frame_count);
+  auto const phase_step = (2.0 * pi * static_cast<double>(frequency)) / static_cast<double>(sample_rate);
+  auto phase = 0.0;
+  for (auto index = std::uint32_t{}; index < frame_count; ++index) {
+    auto const progress = static_cast<double>(index) / static_cast<double>(frame_count);
+    auto const envelope = (1.0 - progress) * (1.0 - progress);
+    result[index] = static_cast<std::float32_t>(std::sin(phase) * envelope * static_cast<double>(gain));
+    phase += phase_step;
+  }
+  return result;
+}
+
 struct active_sound {
   ma_sound sound{};
   std::bool_t initialized{false};
+  std::bool_t loop{false};
+  std::atomic_bool finished{false};
 
   active_sound() = default;
   active_sound(active_sound const&) = delete;
@@ -67,6 +98,27 @@ struct active_sound {
       ma_sound_uninit(&sound);
     }
   }
+
+  static auto end_callback(void* user_data, ma_sound*) -> void {
+    auto* self = static_cast<active_sound*>(user_data);
+    if (self != nullptr) {
+      self->finished.store(true, std::memory_order_release);
+    }
+  }
+};
+
+struct metronome_render_config {
+  std::bool_t enabled{false};
+  std::uint32_t generation{0};
+  std::uint32_t beats_per_bar{4};
+  std::uint64_t frames_per_beat{24000};
+  std::vector<std::float32_t> beat_click{};
+  std::vector<std::float32_t> downbeat_click{};
+};
+
+struct retired_metronome_config {
+  std::unique_ptr<metronome_render_config> config{};
+  std::uint64_t retire_epoch{0};
 };
 
 }
@@ -74,8 +126,11 @@ struct active_sound {
 struct sonus::engine::impl {
   sonus::audio_config config{};
   ma_engine mixer{};
+  ma_context context{};
   ma_device device{};
+  ma_device_id playback_device_id{};
   std::bool_t mixer_initialized{false};
+  std::bool_t context_initialized{false};
   std::bool_t device_initialized{false};
   std::bool_t started{false};
   mutable std::mutex mutex{};
@@ -83,22 +138,19 @@ struct sonus::engine::impl {
   std::unordered_map<sonus::sound_handle, std::unique_ptr<active_sound>> sounds{};
   sonus::sound_handle next_sound_handle{1};
 
+  std::unique_ptr<metronome_render_config> metronome_config{};
+  std::vector<retired_metronome_config> retired_metronome_configs{};
+  std::atomic<metronome_render_config const*> active_metronome_config{nullptr};
   std::atomic_bool metronome_enabled{false};
-  std::atomic<std::uint32_t> metronome_generation{0};
-  std::atomic<std::uint32_t> metronome_bpm{120};
-  std::atomic<std::uint32_t> metronome_beats_per_bar{4};
-  std::atomic<std::uint32_t> metronome_click_frames{1680};
-  std::atomic<std::float32_t> metronome_volume{0.45F};
-  std::atomic<std::float32_t> metronome_beat_frequency{1320.0F};
-  std::atomic<std::float32_t> metronome_downbeat_frequency{1760.0F};
+  std::atomic<std::uint64_t> render_epoch{0};
+  std::uint32_t next_metronome_generation{1};
 
   std::uint32_t observed_metronome_generation{0};
   std::uint32_t beat_index{0};
   std::uint64_t frames_until_next_beat{0};
-  std::uint32_t click_frame_index{0};
-  std::uint32_t click_frames_remaining{0};
-  std::float32_t click_frequency{1320.0F};
-  std::float32_t click_gain{0.0F};
+  std::size_t click_frame_index{0};
+  std::size_t click_frames_remaining{0};
+  std::bool_t click_is_downbeat{false};
 
   impl() = default;
   impl(impl const&) = delete;
@@ -109,12 +161,15 @@ struct sonus::engine::impl {
   }
 
   auto initialize(sonus::audio_config value) -> std::expected<void, modulus::error> {
-    config = value;
+    config = std::move(value);
+    publish_metronome_locked(make_disabled_metronome_config_locked());
 
     auto engine_config = ma_engine_config_init();
     engine_config.noDevice = MA_TRUE;
     engine_config.channels = config.channels;
     engine_config.sampleRate = config.sample_rate;
+    engine_config.periodSizeInFrames = config.period_size_frames;
+    engine_config.periodSizeInMilliseconds = config.period_size_milliseconds;
     engine_config.noAutoStart = MA_TRUE;
 
     auto result = ma_engine_init(&engine_config, &mixer);
@@ -134,10 +189,20 @@ struct sonus::engine::impl {
       device_config.playback.format = ma_format_f32;
       device_config.playback.channels = config.channels;
       device_config.sampleRate = config.sample_rate;
+      device_config.periodSizeInFrames = config.period_size_frames;
+      device_config.periodSizeInMilliseconds = config.period_size_milliseconds;
+      device_config.periods = config.period_count;
+      device_config.performanceProfile = to_miniaudio_profile(config.performance);
       device_config.dataCallback = sonus::engine::impl::device_callback;
       device_config.pUserData = this;
 
-      result = ma_device_init(nullptr, &device_config, &device);
+      auto selected = configure_playback_device(device_config);
+      if (!selected) {
+        shutdown();
+        return selected;
+      }
+
+      result = ma_device_init(context_initialized ? &context : nullptr, &device_config, &device);
       if (result != MA_SUCCESS) {
         shutdown();
         return sonus::detail::fail_void(miniaudio_error(result, "failed to initialize playback device"));
@@ -180,32 +245,65 @@ struct sonus::engine::impl {
   }
 
   auto shutdown() -> void {
-    {
-      auto lock = std::scoped_lock{mutex};
-      if (device_initialized) {
-        if (started) {
-          static_cast<void>(ma_device_stop(&device));
-          started = false;
-        }
-        ma_device_uninit(&device);
-        device_initialized = false;
+    auto lock = std::scoped_lock{mutex};
+    if (device_initialized) {
+      if (started) {
+        static_cast<void>(ma_device_stop(&device));
+        started = false;
       }
-      sounds.clear();
-      if (mixer_initialized) {
-        ma_engine_uninit(&mixer);
-        mixer_initialized = false;
-      }
-      metronome_enabled.store(false, std::memory_order_release);
+      ma_device_uninit(&device);
+      device_initialized = false;
     }
+    sounds.clear();
+    if (mixer_initialized) {
+      ma_engine_uninit(&mixer);
+      mixer_initialized = false;
+    }
+    if (context_initialized) {
+      ma_context_uninit(&context);
+      context_initialized = false;
+    }
+    metronome_enabled.store(false, std::memory_order_release);
+    active_metronome_config.store(nullptr, std::memory_order_release);
+    metronome_config.reset();
+    retired_metronome_configs.clear();
+    reset_metronome_render_state();
+  }
+
+  auto configure_playback_device(ma_device_config& device_config) -> std::expected<void, modulus::error> {
+    if (config.playback_device_name.empty()) {
+      return {};
+    }
+
+    auto context_config = ma_context_config_init();
+    auto result = ma_context_init(nullptr, 0, &context_config, &context);
+    if (result != MA_SUCCESS) {
+      return sonus::detail::fail_void(miniaudio_error(result, "failed to initialize miniaudio context"));
+    }
+    context_initialized = true;
+
+    ma_device_info* playback_devices = nullptr;
+    auto playback_device_count = ma_uint32{};
+    result = ma_context_get_devices(&context, &playback_devices, &playback_device_count, nullptr, nullptr);
+    if (result != MA_SUCCESS) {
+      return sonus::detail::fail_void(miniaudio_error(result, "failed to enumerate playback devices"));
+    }
+
+    for (auto index = ma_uint32{}; index < playback_device_count; ++index) {
+      if (config.playback_device_name == playback_devices[index].name) {
+        playback_device_id = playback_devices[index].id;
+        device_config.playback.pDeviceID = &playback_device_id;
+        return {};
+      }
+    }
+
+    return sonus::detail::fail_void(sonus::detail::error_not_found, "playback device not found: " + config.playback_device_name);
   }
 
   auto set_master_volume(std::float32_t volume) -> std::expected<void, modulus::error> {
-    auto valid = sonus::validate(sonus::audio_config{
-      .sample_rate = config.sample_rate,
-      .channels = config.channels,
-      .master_volume = volume,
-      .no_device = config.no_device,
-    });
+    auto next_config = config;
+    next_config.master_volume = volume;
+    auto valid = sonus::validate(next_config);
     if (!valid) {
       return valid;
     }
@@ -233,16 +331,24 @@ struct sonus::engine::impl {
     }
 
     auto sound = std::make_unique<active_sound>();
+    sound->loop = options.loop;
     auto const path_text = path.string();
     auto flags = static_cast<ma_uint32>(MA_SOUND_FLAG_NO_SPATIALIZATION);
     flags |= options.stream ? MA_SOUND_FLAG_STREAM : MA_SOUND_FLAG_DECODE;
 
     auto lock = std::scoped_lock{mutex};
+    static_cast<void>(collect_finished_locked());
+    collect_retired_metronome_configs_locked();
+
     auto result = ma_sound_init_from_file(&mixer, path_text.c_str(), flags, nullptr, nullptr, &sound->sound);
     if (result != MA_SUCCESS) {
       return sonus::detail::fail<sonus::sound_handle>(miniaudio_error(result, "failed to load sound file"));
     }
     sound->initialized = true;
+    result = ma_sound_set_end_callback(&sound->sound, active_sound::end_callback, sound.get());
+    if (result != MA_SUCCESS) {
+      return sonus::detail::fail<sonus::sound_handle>(miniaudio_error(result, "failed to set sound end callback"));
+    }
     ma_sound_set_volume(&sound->sound, options.volume);
     ma_sound_set_looping(&sound->sound, options.loop ? MA_TRUE : MA_FALSE);
     result = ma_sound_start(&sound->sound);
@@ -250,12 +356,12 @@ struct sonus::engine::impl {
       return sonus::detail::fail<sonus::sound_handle>(miniaudio_error(result, "failed to start sound file"));
     }
 
-    auto handle = next_sound_handle++;
-    if (next_sound_handle == 0) {
-      next_sound_handle = 1;
+    auto handle = allocate_sound_handle_locked();
+    if (!handle) {
+      return sonus::detail::fail<sonus::sound_handle>(handle.error());
     }
-    sounds.emplace(handle, std::move(sound));
-    return handle;
+    sounds.emplace(*handle, std::move(sound));
+    return *handle;
   }
 
   auto stop_sound(sonus::sound_handle handle) -> std::expected<void, modulus::error> {
@@ -280,32 +386,164 @@ struct sonus::engine::impl {
     sounds.clear();
   }
 
+  auto is_sound_playing(sonus::sound_handle handle) -> std::expected<std::bool_t, modulus::error> {
+    if (handle == 0) {
+      return sonus::detail::fail<std::bool_t>(sonus::detail::error_invalid_argument, "sound handle must not be zero");
+    }
+    auto lock = std::scoped_lock{mutex};
+    auto found = sounds.find(handle);
+    if (found == sounds.end()) {
+      return sonus::detail::fail<std::bool_t>(sonus::detail::error_not_found, "sound handle not found");
+    }
+    if (sound_finished(*found->second)) {
+      sounds.erase(found);
+      return false;
+    }
+    return ma_sound_is_playing(&found->second->sound) == MA_TRUE;
+  }
+
+  auto collect_finished_sounds() -> std::uint64_t {
+    auto lock = std::scoped_lock{mutex};
+    auto const collected = collect_finished_locked();
+    collect_retired_metronome_configs_locked();
+    return collected;
+  }
+
+  auto active_sound_count() -> std::uint64_t {
+    auto lock = std::scoped_lock{mutex};
+    static_cast<void>(collect_finished_locked());
+    collect_retired_metronome_configs_locked();
+    return sounds.size();
+  }
+
   auto store_metronome(sonus::metronome_config value, std::bool_t enable) -> std::expected<void, modulus::error> {
     auto valid = sonus::validate(value);
     if (!valid) {
       return valid;
     }
 
+    auto next = make_metronome_config(value, enable);
+    if (!next) {
+      return sonus::detail::fail_void(next.error());
+    }
+
+    auto lock = std::scoped_lock{mutex};
+    publish_metronome_locked(std::move(*next));
+    collect_retired_metronome_configs_locked();
+    return {};
+  }
+
+  auto update_metronome(sonus::metronome_config value) -> std::expected<void, modulus::error> {
+    return store_metronome(value, metronome_enabled.load(std::memory_order_acquire));
+  }
+
+  auto stop_metronome() -> void {
+    auto lock = std::scoped_lock{mutex};
+    publish_metronome_locked(make_disabled_metronome_config_locked());
+    collect_retired_metronome_configs_locked();
+  }
+
+  auto make_metronome_config(sonus::metronome_config value, std::bool_t enable) -> std::expected<std::unique_ptr<metronome_render_config>, modulus::error> {
     auto click_frames = static_cast<std::uint64_t>(config.sample_rate) * static_cast<std::uint64_t>(value.click_duration.count()) / 1000U;
     click_frames = std::clamp<std::uint64_t>(click_frames, 1U, std::numeric_limits<std::uint32_t>::max());
+    auto frames_per_beat = std::max<std::uint64_t>(1U, static_cast<std::uint64_t>(std::llround((static_cast<double>(config.sample_rate) * 60.0) / static_cast<double>(value.bpm))));
 
-    metronome_bpm.store(value.bpm, std::memory_order_release);
-    metronome_beats_per_bar.store(value.beats_per_bar, std::memory_order_release);
-    metronome_click_frames.store(static_cast<std::uint32_t>(click_frames), std::memory_order_release);
-    metronome_volume.store(value.volume, std::memory_order_release);
-    metronome_beat_frequency.store(value.beat_frequency_hz, std::memory_order_release);
-    metronome_downbeat_frequency.store(value.downbeat_frequency_hz, std::memory_order_release);
+    auto result = std::make_unique<metronome_render_config>();
+    result->enabled = enable;
+    result->beats_per_bar = value.beats_per_bar;
+    result->frames_per_beat = frames_per_beat;
     if (enable) {
-      metronome_enabled.store(true, std::memory_order_release);
+      result->beat_click = make_click_samples(config.sample_rate, static_cast<std::uint32_t>(click_frames), value.beat_frequency_hz, value.volume * 0.64F);
+      result->downbeat_click = make_click_samples(config.sample_rate, static_cast<std::uint32_t>(click_frames), value.downbeat_frequency_hz, value.volume);
     }
-    metronome_generation.fetch_add(1, std::memory_order_acq_rel);
-    return {};
+    return std::move(result);
+  }
+
+  auto make_disabled_metronome_config_locked() -> std::unique_ptr<metronome_render_config> {
+    auto result = std::make_unique<metronome_render_config>();
+    result->enabled = false;
+    return result;
+  }
+
+  auto publish_metronome_locked(std::unique_ptr<metronome_render_config> next) -> void {
+    next->generation = next_metronome_generation++;
+    if (next_metronome_generation == 0U) {
+      next_metronome_generation = 1U;
+    }
+
+    auto previous = std::move(metronome_config);
+    auto* next_pointer = next.get();
+    metronome_config = std::move(next);
+    active_metronome_config.store(next_pointer, std::memory_order_release);
+    metronome_enabled.store(next_pointer->enabled, std::memory_order_release);
+    if (previous) {
+      retired_metronome_configs.push_back(retired_metronome_config{
+        .config = std::move(previous),
+        .retire_epoch = render_epoch.load(std::memory_order_acquire),
+      });
+    }
+  }
+
+  auto collect_retired_metronome_configs_locked() -> void {
+    auto const completed_epoch = render_epoch.load(std::memory_order_acquire);
+    auto first_removed = std::remove_if(retired_metronome_configs.begin(), retired_metronome_configs.end(), [completed_epoch](retired_metronome_config const& retired) {
+      return retired.retire_epoch < completed_epoch;
+    });
+    retired_metronome_configs.erase(first_removed, retired_metronome_configs.end());
+  }
+
+  auto allocate_sound_handle_locked() -> std::expected<sonus::sound_handle, modulus::error> {
+    if (sounds.size() >= static_cast<std::size_t>(std::numeric_limits<sonus::sound_handle>::max() - 1U)) {
+      return sonus::detail::fail<sonus::sound_handle>(sonus::detail::error_internal, "sound handle space exhausted");
+    }
+
+    auto attempts = std::size_t{};
+    auto const max_attempts = sounds.size() + 1U;
+    while (attempts < max_attempts) {
+      auto handle = next_sound_handle++;
+      if (next_sound_handle == 0U) {
+        next_sound_handle = 1U;
+      }
+      if (!sounds.contains(handle)) {
+        return handle;
+      }
+      ++attempts;
+    }
+
+    return sonus::detail::fail<sonus::sound_handle>(sonus::detail::error_internal, "failed to allocate sound handle");
+  }
+
+  static auto sound_finished(active_sound const& sound) -> std::bool_t {
+    return !sound.loop && (sound.finished.load(std::memory_order_acquire) || ma_sound_at_end(&sound.sound) == MA_TRUE);
+  }
+
+  auto collect_finished_locked() -> std::uint64_t {
+    auto collected = std::uint64_t{};
+    auto current = sounds.begin();
+    while (current != sounds.end()) {
+      if (sound_finished(*current->second)) {
+        current = sounds.erase(current);
+        ++collected;
+      } else {
+        ++current;
+      }
+    }
+    return collected;
   }
 
   auto render_to(std::float32_t* output, std::uint64_t frame_count) -> ma_result {
     if (output == nullptr || frame_count == 0U) {
       return MA_SUCCESS;
     }
+
+    struct epoch_guard {
+      std::atomic<std::uint64_t>& epoch;
+
+      ~epoch_guard() {
+        epoch.fetch_add(1, std::memory_order_acq_rel);
+      }
+    } guard{render_epoch};
+
     auto const sample_count = frame_count * config.channels;
     std::fill(output, output + sample_count, 0.0F);
     auto result = ma_engine_read_pcm_frames(&mixer, output, frame_count, nullptr);
@@ -318,51 +556,39 @@ struct sonus::engine::impl {
   }
 
   auto mix_metronome(std::float32_t* output, std::uint64_t frame_count) -> void {
-    auto const generation = metronome_generation.load(std::memory_order_acquire);
-    auto const enabled = metronome_enabled.load(std::memory_order_acquire);
-    if (!enabled) {
-      observed_metronome_generation = generation;
-      beat_index = 0;
-      frames_until_next_beat = 0;
-      click_frame_index = 0;
-      click_frames_remaining = 0;
+    auto const* metro = active_metronome_config.load(std::memory_order_acquire);
+    if (metro == nullptr || !metro->enabled) {
+      if (metro != nullptr) {
+        observed_metronome_generation = metro->generation;
+      }
+      reset_metronome_render_state();
       return;
     }
-    if (observed_metronome_generation != generation) {
-      observed_metronome_generation = generation;
-      beat_index = 0;
-      frames_until_next_beat = 0;
-      click_frame_index = 0;
-      click_frames_remaining = 0;
+    if (observed_metronome_generation != metro->generation) {
+      observed_metronome_generation = metro->generation;
+      reset_metronome_render_state();
     }
 
-    auto const bpm = std::max<std::uint32_t>(1U, metronome_bpm.load(std::memory_order_acquire));
-    auto const beats_per_bar = std::max<std::uint32_t>(1U, metronome_beats_per_bar.load(std::memory_order_acquire));
-    auto const click_frames = std::max<std::uint32_t>(1U, metronome_click_frames.load(std::memory_order_acquire));
-    auto const volume = metronome_volume.load(std::memory_order_acquire);
-    auto const beat_frequency = metronome_beat_frequency.load(std::memory_order_acquire);
-    auto const downbeat_frequency = metronome_downbeat_frequency.load(std::memory_order_acquire);
-    auto const frames_per_beat = std::max<std::uint64_t>(1U, static_cast<std::uint64_t>(std::llround((static_cast<double>(config.sample_rate) * 60.0) / static_cast<double>(bpm))));
-
     for (auto frame = std::uint64_t{}; frame < frame_count; ++frame) {
       if (frames_until_next_beat == 0U) {
         auto const downbeat = beat_index == 0U;
         click_frame_index = 0;
-        click_frames_remaining = click_frames;
-        click_frequency = downbeat ? downbeat_frequency : beat_frequency;
-        click_gain = volume * (downbeat ? 1.0F : 0.64F);
-        beat_index = (beat_index + 1U) % beats_per_bar;
-        frames_until_next_beat = frames_per_beat;
+        click_is_downbeat = downbeat;
+        click_frames_remaining = downbeat ? metro->downbeat_click.size() : metro->beat_click.size();
+        beat_index = (beat_index + 1U) % std::max<std::uint32_t>(1U, metro->beats_per_bar);
+        frames_until_next_beat = metro->frames_per_beat;
       }
 
       auto sample = 0.0F;
       if (click_frames_remaining > 0U) {
-        auto const t = static_cast<double>(click_frame_index) / static_cast<double>(config.sample_rate);
-        auto const progress = static_cast<double>(click_frame_index) / static_cast<double>(click_frames);
-        auto const envelope = (1.0 - progress) * (1.0 - progress);
-        sample = static_cast<std::float32_t>(std::sin(2.0 * pi * static_cast<double>(click_frequency) * t) * envelope * static_cast<double>(click_gain));
-        ++click_frame_index;
-        --click_frames_remaining;
+        auto const& click = click_is_downbeat ? metro->downbeat_click : metro->beat_click;
+        if (click_frame_index < click.size()) {
+          sample = click[click_frame_index];
+          ++click_frame_index;
+          --click_frames_remaining;
+        } else {
+          click_frames_remaining = 0;
+        }
       }
 
       if (sample != 0.0F) {
@@ -375,6 +601,14 @@ struct sonus::engine::impl {
     }
   }
 
+  auto reset_metronome_render_state() -> void {
+    beat_index = 0;
+    frames_until_next_beat = 0;
+    click_frame_index = 0;
+    click_frames_remaining = 0;
+    click_is_downbeat = false;
+  }
+
   static auto device_callback(ma_device* device, void* output, void const*, ma_uint32 frame_count) -> void {
     auto* self = static_cast<sonus::engine::impl*>(device == nullptr ? nullptr : device->pUserData);
     if (self == nullptr || output == nullptr) {
@@ -398,6 +632,24 @@ auto sonus::validate(sonus::audio_config const& config) -> std::expected<void, m
   if (!valid_unit_interval(config.master_volume)) {
     return sonus::detail::fail_void(invalid("audio master_volume must be between 0 and 1"));
   }
+  if (contains_null(config.playback_device_name)) {
+    return sonus::detail::fail_void(invalid("audio playback_device_name must not contain null bytes"));
+  }
+  if (config.no_device && !config.playback_device_name.empty()) {
+    return sonus::detail::fail_void(invalid("audio playback_device_name requires a playback device"));
+  }
+  if (config.period_size_frames != 0U && config.period_size_milliseconds != 0U) {
+    return sonus::detail::fail_void(invalid("audio period_size_frames and period_size_milliseconds are mutually exclusive"));
+  }
+  if (config.period_size_frames > 262144U) {
+    return sonus::detail::fail_void(invalid("audio period_size_frames must be no greater than 262144"));
+  }
+  if (config.period_size_milliseconds > 1000U) {
+    return sonus::detail::fail_void(invalid("audio period_size_milliseconds must be no greater than 1000"));
+  }
+  if (config.period_count > 16U) {
+    return sonus::detail::fail_void(invalid("audio period_count must be no greater than 16"));
+  }
   return {};
 }
 
@@ -433,7 +685,7 @@ auto sonus::engine::create(sonus::audio_config config) -> std::expected<sonus::e
     return sonus::detail::fail<sonus::engine>(valid.error());
   }
   auto implementation = std::make_unique<sonus::engine::impl>();
-  auto initialized = implementation->initialize(config);
+  auto initialized = implementation->initialize(std::move(config));
   if (!initialized) {
     return sonus::detail::fail<sonus::engine>(initialized.error());
   }
@@ -504,6 +756,21 @@ auto sonus::engine::stop_all() -> void {
   }
 }
 
+auto sonus::engine::is_playing(sonus::sound_handle handle) -> std::expected<std::bool_t, modulus::error> {
+  if (!implementation_) {
+    return sonus::detail::fail<std::bool_t>(sonus::detail::error_invalid_argument, "audio engine is empty");
+  }
+  return implementation_->is_sound_playing(handle);
+}
+
+auto sonus::engine::collect_finished() -> std::uint64_t {
+  return implementation_ ? implementation_->collect_finished_sounds() : 0U;
+}
+
+auto sonus::engine::active_sound_count() -> std::uint64_t {
+  return implementation_ ? implementation_->active_sound_count() : 0U;
+}
+
 auto sonus::engine::start_metronome(sonus::metronome_config config) -> std::expected<void, modulus::error> {
   if (!implementation_) {
     return sonus::detail::fail_void(sonus::detail::error_invalid_argument, "audio engine is empty");
@@ -515,15 +782,13 @@ auto sonus::engine::update_metronome(sonus::metronome_config config) -> std::exp
   if (!implementation_) {
     return sonus::detail::fail_void(sonus::detail::error_invalid_argument, "audio engine is empty");
   }
-  return implementation_->store_metronome(config, false);
+  return implementation_->update_metronome(config);
 }
 
 auto sonus::engine::stop_metronome() -> void {
-  if (!implementation_) {
-    return;
+  if (implementation_) {
+    implementation_->stop_metronome();
   }
-  implementation_->metronome_enabled.store(false, std::memory_order_release);
-  implementation_->metronome_generation.fetch_add(1, std::memory_order_acq_rel);
 }
 
 auto sonus::engine::metronome_active() const -> std::bool_t {
@@ -540,7 +805,10 @@ auto sonus::engine::render(std::float32_t* output, std::uint64_t frame_count) ->
   if (output == nullptr) {
     return sonus::detail::fail_void(sonus::detail::error_invalid_argument, "manual render output must not be null");
   }
-  auto lock = std::scoped_lock{implementation_->render_mutex};
+  if (implementation_->config.channels != 0U && frame_count > std::numeric_limits<std::uint64_t>::max() / implementation_->config.channels) {
+    return sonus::detail::fail_void(sonus::detail::error_invalid_argument, "manual render frame_count is too large");
+  }
+  auto lock = std::scoped_lock{implementation_->mutex, implementation_->render_mutex};
   auto result = implementation_->render_to(output, frame_count);
   if (result != MA_SUCCESS) {
     return sonus::detail::fail_void(miniaudio_error(result, "failed to render audio"));