Migrate selected models to spec v1

CMakeLists.txt

@@ -367,11 +367,9 @@ audiocpp_configure_runtime_object(engine_model_marblenet_vad)
 audiocpp_add_model(roformer
     SOURCES
         src/models/roformer/assets.cpp
-        src/models/roformer/loader.cpp
         src/models/roformer/runtime.cpp
         src/models/roformer/session.cpp
     INCLUDES
-        engine/models/roformer/loader.h
         engine/models/roformer/session.h
     LOADERS
         engine::models::roformer::make_mel_band_roformer_loader
@@ -387,10 +385,9 @@ audiocpp_add_model(demucs
         src/models/demucs/frontend.cpp
         src/models/demucs/pipeline.cpp
         src/models/demucs/postprocess.cpp
-        src/models/demucs/loader.cpp
         src/models/demucs/session.cpp
     INCLUDES
-        engine/models/demucs/loader.h
+        engine/models/demucs/session.h
     LOADERS
         engine::models::demucs::make_htdemucs_loader
     ALIASES
@@ -721,12 +718,11 @@ audiocpp_add_model(heartmula
         src/models/heartmula/assets.cpp
         src/models/heartmula/codec.cpp
         src/models/heartmula/generator.cpp
-        src/models/heartmula/loader.cpp
         src/models/heartmula/mula.cpp
         src/models/heartmula/session.cpp
         src/models/heartmula/tokenizer_text.cpp
     INCLUDES
-        engine/models/heartmula/loader.h
+        engine/models/heartmula/session.h
     LOADERS
         engine::models::heartmula::make_heartmula_loader
 )
@@ -772,10 +768,9 @@ audiocpp_add_model(hviske_asr
         src/models/hviske_asr/encoder.cpp
         src/models/hviske_asr/decoder.cpp
         src/models/hviske_asr/session.cpp
-        src/models/hviske_asr/loader.cpp
         src/models/hviske_asr/weights.cpp
     INCLUDES
-        engine/models/hviske_asr/loader.h
+        engine/models/hviske_asr/session.h
     LOADERS
         engine::models::hviske_asr::make_hviske_asr_loader
 )
@@ -992,9 +987,8 @@ audiocpp_add_model(seed_vc
         src/models/seed_vc/v1_cfm.cpp
         src/models/seed_vc/v2_cfm.cpp
         src/models/seed_vc/session.cpp
-        src/models/seed_vc/loader.cpp
     INCLUDES
-        engine/models/seed_vc/loader.h
+        engine/models/seed_vc/session.h
     LOADERS
         engine::models::seed_vc::make_seed_vc_loader
 )

docs/asr.md

@@ -203,9 +203,17 @@ completed GGUF can therefore be moved, renamed, and passed directly to `--model`
 | `--top-p` | float | model default | Nucleus sampling limit. |
 | `--seed` | integer | random if omitted | Sampling seed. |
 | `--audio-chunk-mode` | `auto`, `fixed`, `none` | `auto` | Long-audio chunking mode. `auto` uses the model clip limit and speech-energy boundaries when chunking is needed. |
-| `--audio-chunk-seconds` | float seconds | model config | Fixed audio chunk duration. |
+| `--request-option audio_chunk_duration_sec=<seconds>` | float seconds | model config | Fixed audio chunk duration. |
 | `--text-out` | TXT path | not set | Transcript output. The transcript is also printed to stdout. |
 
+Compatibility aliases for existing requests:
+
+| Legacy option | Current option |
+|---|---|
+| `audio_chunk_seconds` | `audio_chunk_duration_sec` |
+| `audio_chunk_duration_seconds` | `audio_chunk_duration_sec` |
+| `audio_chunk_duration` | `audio_chunk_duration_sec` |
+
 ## Nemotron ASR
 
 Nemotron ASR is an NVIDIA Nemotron 3.5 ASR RNNT model with offline and streaming sessions. It supports language prompts and optional token timestamp output.

docs/audio_tools.md

@@ -147,6 +147,13 @@ audiocpp_cli --task sep --family htdemucs --model models/htdemucs --backend cuda
 | `--audio` | 44.1 kHz WAV path | required | Input music mixture. |
 | `--out-dir` | directory | required | Directory for separated stems. |
 | `--backend` | `cpu`, `cuda`, `vulkan`, `metal`, `best` | `cpu` | Compute backend. |
+| `--session-option htdemucs.weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | backend-dependent | Weight storage type. Defaults to `f32` for host graph planning, `f16` on CUDA, and `native` otherwise. |
+
+Schema-v1 option compatibility:
+
+| Legacy/session input | Schema-v1 option | Notes |
+|---|---|---|
+| `weight_type` | `htdemucs.weight_type` | Accepted as a compatibility alias for direct session-option callers. Prefer the family-prefixed form. |
 
 ## BS-RoFormer
 
@@ -218,7 +225,7 @@ Mel-Band RoFormer is wired as a vocal/source-separation model. The CLI uses the
 | Modes | `offline` |
 | Input | 44.1 kHz music mixture WAV through `--audio` |
 | Output | Named separated artifacts under `--out-dir` |
-| Notes | Chunking/overlap behavior is internal to the integration; no user chunk option is exposed here |
+| Notes | Uses the package overlap count by default; `mel_band_roformer.num_overlap` can lower the overlap for faster inference with a quality tradeoff |
 
 ```bash
 audiocpp_cli --task sep --family mel_band_roformer --model models/mel-roformer-mlx --backend cuda --audio song_44k.wav --out-dir stems
@@ -229,5 +236,14 @@ audiocpp_cli --task sep --family mel_band_roformer --model models/mel-roformer-m
 | `--audio` | 44.1 kHz WAV path | required | Input music mixture. |
 | `--out-dir` | directory | required | Directory for separated outputs. |
 | `--backend` | `cpu`, `cuda`, `vulkan`, `metal`, `best` | `cpu` | Compute backend. |
+| `--session-option mel_band_roformer.weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | backend-dependent | Weight storage type. Defaults to `f32` when the backend requires a host graph plan, otherwise `native`. |
+| `--session-option mel_band_roformer.num_overlap=<n>` | integer `>= 1` | package config | Number of overlapping inference windows. Lower values improve throughput but can reduce boundary quality. |
+
+Schema-v1 option compatibility:
+
+| Legacy/session input | Schema-v1 option | Notes |
+|---|---|---|
+| `weight_type` | `mel_band_roformer.weight_type` | Accepted as a compatibility alias for direct session-option callers. Prefer the family-prefixed form. |
+| `num_overlap` | `mel_band_roformer.num_overlap` | Accepted as a compatibility alias for direct session-option callers. Prefer the family-prefixed form. |
 
 For backend weight-type controls, use `audiocpp_cli --inspect --model <model-dir> --family <family>`.

docs/models/seed_vc.md

@@ -31,7 +31,7 @@ Use the V2 voice-conversion path for speech voice conversion. This route uses se
 | Source audio | Required |
 | Target voice reference | Required |
 | Pitch controls | Not used |
-| Style conversion | `convert_style=true` is parsed but not implemented |
+| Style conversion | Not exposed in the current C++ route |
 
 ```bash
 audiocpp_cli --task vc --family seed_vc --model models/SeedVC-MLX --backend cuda --task-route v2_vc --audio source.wav --voice-ref target.wav --out converted.wav
@@ -41,15 +41,11 @@ audiocpp_cli --task vc --family seed_vc --model models/SeedVC-MLX --backend cuda
 |---|---|---:|---|
 | `--num-inference-steps` | integer | `30` | V2 CFM denoising steps. |
 | `--request-option length_adjust=<float>` | float | `1.0` | Stretch or compress generated duration. |
-| `--request-option intelligibility_cfg_rate=<float>` | float | `0.7` | CFG strength for source-content intelligibility. |
-| `--request-option similarity_cfg_rate=<float>` | float | `0.7` | CFG strength for target-speaker similarity. |
-| `--temperature` | float | `1.0` | V2 AR sampling temperature. |
-| `--top-p` | `0..1` | `0.9` | V2 AR nucleus sampling. |
-| `--repetition-penalty` | positive float | `1.0` | V2 AR repetition penalty. |
+| `--request-option intelligibility_guidance_scale=<float>` | float | `0.7` | CFG strength for source-content intelligibility. |
+| `--request-option similarity_guidance_scale=<float>` | float | `0.7` | CFG strength for target-speaker similarity. |
 | `--seed` | integer | random if omitted | Seed for V2 random sampling/noise. |
-| `--request-option anonymization_only=true|false` | bool | `false` | Use randomized voice conditioning instead of target-style conditioning. |
-| `--request-option convert_style=true|false` | bool | `false` | Parsed option; `true` is not implemented in the current C++ route. |
-| `--request-option noise_file=<path>` | path | empty | Optional deterministic noise input for validation. |
+| `--request-option voice_anonymization=true|false` | bool | `false` | Use randomized voice conditioning instead of target-speaker conditioning. |
+| `--request-option noise_path=<path>` | path | empty | Optional deterministic noise input for validation. |
 
 ## V1 Whisper + BigVGAN Voice Conversion
 
@@ -72,7 +68,7 @@ audiocpp_cli --task vc --family seed_vc --model models/SeedVC-MLX --backend cuda
 |---|---|---:|---|
 | `--num-inference-steps` | integer | `30` | V1 CFM denoising steps. |
 | `--request-option length_adjust=<float>` | float | `1.0` | Stretch or compress generated duration. |
-| `--request-option inference_cfg_rate=<float>` | float | `0.7` | V1 CFM guidance strength. |
+| `--request-option inference_guidance_scale=<float>` | float | `0.7` | V1 CFM guidance strength. |
 | `--seed` | integer | random if omitted | Seed for V1 random noise. |
 
 ## V1 XLSR + HiFT Voice Conversion
@@ -96,7 +92,7 @@ audiocpp_cli --task vc --family seed_vc --model models/SeedVC-MLX --backend cuda
 |---|---|---:|---|
 | `--num-inference-steps` | integer | `30` | V1 CFM denoising steps. |
 | `--request-option length_adjust=<float>` | float | `1.0` | Stretch or compress generated duration. |
-| `--request-option inference_cfg_rate=<float>` | float | `0.7` | V1 CFM guidance strength. |
+| `--request-option inference_guidance_scale=<float>` | float | `0.7` | V1 CFM guidance strength. |
 | `--seed` | integer | random if omitted | Seed for V1 random noise. |
 
 ## V1 Singing Voice Conversion
@@ -110,7 +106,7 @@ Use this route for singing voice conversion. It supports the V1 F0 and pitch con
 | Source singing | Required |
 | Target singer reference | Required |
 | F0 extraction | Optional through `f0_condition` |
-| Pitch controls | `semi_tone_shift`, `auto_f0_adjust` |
+| Pitch controls | `semitone_shift`, `auto_f0_adjust` |
 
 ```bash
 audiocpp_cli --task svc --family seed_vc --model models/SeedVC-MLX --backend cuda --task-route v1_svc --audio singing.wav --voice-ref target.wav --out svc.wav
@@ -120,10 +116,10 @@ audiocpp_cli --task svc --family seed_vc --model models/SeedVC-MLX --backend cud
 |---|---|---:|---|
 | `--num-inference-steps` | integer | `30` | V1 CFM denoising steps. |
 | `--request-option length_adjust=<float>` | float | `1.0` | Stretch or compress generated duration. |
-| `--request-option inference_cfg_rate=<float>` | float | `0.7` | V1 CFM guidance strength. |
+| `--request-option inference_guidance_scale=<float>` | float | `0.7` | V1 CFM guidance strength. |
 | `--request-option f0_condition=true|false` | bool | `false` | Enable F0-conditioned conversion. |
 | `--request-option auto_f0_adjust=true|false` | bool | `false` | Automatically adjust F0 when F0 conditioning is enabled. |
-| `--request-option semi_tone_shift=<n>` | integer | `0` | Shift pitch by semitones when F0 conditioning is enabled. |
+| `--request-option semitone_shift=<n>` | integer | `0` | Shift pitch by semitones when F0 conditioning is enabled. |
 | `--seed` | integer | random if omitted | Seed for V1 random noise. |
 
 ## Shared Controls
@@ -134,3 +130,16 @@ audiocpp_cli --task svc --family seed_vc --model models/SeedVC-MLX --backend cud
 | `--audio` | WAV path | required | Source speech or singing audio. |
 | `--voice-ref` | WAV path | required | Target voice or singer reference. |
 | `--session-option seed_vc.weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | `native` | Weight storage type. |
+
+## Compatibility
+
+The schema-v1 option names are the preferred names. Existing local requests using the old names are still accepted through this compatibility map:
+
+| Old request option | New request option |
+|---|---|
+| `inference_cfg_rate` | `inference_guidance_scale` |
+| `intelligibility_cfg_rate` | `intelligibility_guidance_scale` |
+| `similarity_cfg_rate` | `similarity_guidance_scale` |
+| `anonymization_only` | `voice_anonymization` |
+| `noise_file` | `noise_path` |
+| `semi_tone_shift` | `semitone_shift` |

docs/music_generation.md

@@ -110,17 +110,39 @@ audiocpp_cli --task gen --family heartmula --model models/HeartMuLa --backend cu
 | `--text` | text | required | Music prompt or short description. |
 | `--lyrics` | text | empty string | Lyrics for generated music. |
 | `--request-option tags=<text>` | comma-separated text | required | Music tags; the model path wraps them as tag tokens internally. |
-| `--duration-seconds` | seconds | `120` | Maximum generated duration. |
+| `--request-option duration_sec=<seconds>` | seconds | `120` | Maximum generated duration. |
 | `--temperature` | float | `1.0` | Music-token sampling temperature. |
 | `--top-k` | integer | `50` | Music-token top-k sampling limit. |
 | `--guidance-scale` | float | `1.5` | MuLa classifier-free guidance scale. |
 | `--num-inference-steps` | integer | `10` | Codec flow solver steps. |
-| `--request-option codec_duration=<seconds>` | seconds | `29.76` | Codec detokenization chunk duration. |
+| `--request-option codec_duration_sec=<seconds>` | seconds | `29.76` | Codec detokenization chunk duration. |
 | `--request-option codec_guidance_scale=<float>` | float | `1.25` | Codec classifier-free guidance scale. |
 | `--request-option infinite_mode=true|false` | bool | `false` | Generate long outputs by splitting lyrics into bounded HeartMuLa requests. |
 | `--text-chunk-size` | chars | `4096` | Text chunk size for infinite mode. |
-| `--request-option infinite_chunk_audio_length_ms=<n>` | milliseconds | `240000` | Per-chunk audio cap for infinite mode. |
+| `--request-option infinite_chunk_audio_duration_ms=<n>` | milliseconds | `240000` | Per-chunk audio cap for infinite mode. |
 | `--seed` | integer | `1234` | Generation seed. |
+| `--session-option heartmula.weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | `native` | MuLa and codec weight storage type. |
+| `--session-option heartmula.generator_weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | `heartmula.weight_type` or `native` | MuLa music-token generator weight storage type. |
+| `--session-option heartmula.codec_weight_type=<type>` | `native`, `f32`, `f16`, `bf16`, `q8_0` | `heartmula.weight_type` or `native` | Codec weight storage type. |
 | `--session-option heartmula.mem_saver=true|false` | bool | `false` | Release staged graph/cache state after AR/codec phases and infinite-mode chunks to reduce resident VRAM. Later requests may rebuild released graphs. |
 
-For backend weight-type controls, use `audiocpp_cli --inspect --model <model-dir> --family <family>`.
+Compatibility mapping:
+
+| Legacy option | Schema-v1 option |
+|---|---|
+| `duration_seconds` | `duration_sec` |
+| `codec_duration` | `codec_duration_sec` |
+| `infinite_chunk_audio_length_ms` | `infinite_chunk_audio_duration_ms` |
+| `heartmula.mula_weight_type` | `heartmula.generator_weight_type` |
+| `heartmula.mula_weight_context_mb` | `heartmula.generator_weight_context_mb` |
+| `heartmula.mula_constant_context_mb` | `heartmula.generator_constant_context_mb` |
+| `heartmula.mula_backbone_prefill_graph_arena_mb` | `heartmula.backbone_prefill_graph_arena_mb` |
+| `heartmula.mula_backbone_step_graph_arena_mb` | `heartmula.backbone_step_graph_arena_mb` |
+| `heartmula.mula_decoder_prefill_graph_arena_mb` | `heartmula.decoder_prefill_graph_arena_mb` |
+| `heartmula.mula_decoder_step_graph_arena_mb` | `heartmula.decoder_step_graph_arena_mb` |
+| `heartmula.mula_frame_embedding_graph_arena_mb` | `heartmula.frame_embedding_graph_arena_mb` |
+| `heartmula.codec_flow_estimator_graph_arena_mb` | `heartmula.flow_estimator_graph_arena_mb` |
+| `heartmula.codec_conditioning_graph_arena_mb` | `heartmula.conditioning_graph_arena_mb` |
+| `heartmula.codec_scalar_decoder_graph_arena_mb` | `heartmula.scalar_decoder_graph_arena_mb` |
+
+For the full backend memory-arena controls, use `audiocpp_cli --help --model <model-dir> --family heartmula`.

include/engine/framework/runtime/options.h

@@ -41,6 +41,10 @@ std::optional<float> parse_finite_float_option(
     const std::unordered_map<std::string, std::string> & options,
     std::initializer_list<std::string_view> keys);
 
+std::optional<float> parse_positive_finite_float_option(
+    const std::unordered_map<std::string, std::string> & options,
+    std::initializer_list<std::string_view> keys);
+
 std::optional<uint32_t> parse_u32_option(
     const std::unordered_map<std::string, std::string> & options,
     std::initializer_list<std::string_view> keys);
@@ -69,6 +73,13 @@ assets::TensorStorageType parse_tensor_storage_option(
     assets::TensorStorageType fallback,
     std::initializer_list<assets::TensorStorageType> allowed);
 
+assets::TensorStorageType parse_tensor_storage_option(
+    const std::unordered_map<std::string, std::string> & options,
+    std::string_view key,
+    std::string_view fallback_key,
+    assets::TensorStorageType fallback,
+    std::initializer_list<assets::TensorStorageType> allowed);
+
 uint32_t random_u32_seed();
 uint64_t random_u64_seed();
 

include/engine/framework/runtime/spec_backed_model.h

@@ -6,6 +6,7 @@
 
 #include <filesystem>
 #include <functional>
+#include <initializer_list>
 #include <memory>
 #include <stdexcept>
 #include <string>
@@ -15,6 +16,11 @@
 
 namespace engine::runtime {
 
+struct OptionV1CompatibilityAlias {
+    std::string legacy_key;
+    std::string current_key;
+};
+
 template <typename Assets>
 struct SpecBackedVoiceModelConfig {
     std::string family;
@@ -59,6 +65,42 @@ inline void validate_spec_backed_request_options(
     }
 }
 
+inline std::unordered_map<std::string, std::string> apply_option_v1_compatibility(
+    std::unordered_map<std::string, std::string> options,
+    std::initializer_list<OptionV1CompatibilityAlias> aliases,
+    std::string_view model_name,
+    std::string_view scope_name) {
+    for (const auto & alias : aliases) {
+        auto legacy = options.find(alias.legacy_key);
+        if (legacy == options.end()) {
+            continue;
+        }
+        auto current = options.find(alias.current_key);
+        if (current != options.end()) {
+            throw std::runtime_error(
+                std::string(model_name) + " " + std::string(scope_name) +
+                " options contain both " + alias.legacy_key + " and " +
+                alias.current_key + "; use " + alias.current_key);
+        }
+        std::string value = std::move(legacy->second);
+        options.erase(legacy);
+        options.emplace(alias.current_key, std::move(value));
+    }
+    return options;
+}
+
+inline SessionOptions apply_option_v1_compatibility(
+    SessionOptions options,
+    std::initializer_list<OptionV1CompatibilityAlias> aliases,
+    std::string_view model_name) {
+    options.options = apply_option_v1_compatibility(
+        std::move(options.options),
+        aliases,
+        model_name,
+        "session");
+    return options;
+}
+
 template <typename Assets>
 class SpecBackedLoadedVoiceModel final : public ILoadedVoiceModel {
 public:

include/engine/models/demucs/assets.h

@@ -2,8 +2,8 @@
 
 #include "engine/framework/assets/resource_bundle.h"
 #include "engine/framework/assets/tensor_source.h"
-#include "engine/framework/runtime/model.h"
 
+#include <filesystem>
 #include <memory>
 #include <string>
 #include <vector>
@@ -83,6 +83,6 @@ struct HTDemucsAssets {
 };
 
 void validate_demucs_weight_storage_type(assets::TensorStorageType storage_type);
-std::shared_ptr<const HTDemucsAssets> load_htdemucs_assets(const runtime::ModelLoadRequest & request);
+std::shared_ptr<const HTDemucsAssets> load_htdemucs_assets(const std::filesystem::path & model_path);
 
 }  // namespace engine::models::demucs