feat: support separate codec GGUF via --codec-model

[jadsongmatos]

Summary

Add --codec-model <path> CLI flag to load codec weights from a separate GGUF file instead of the main model file.

Motivation

When distributing models as split files (main model + codec in separate GGUFs), the current code only supports loading the codec from the same GGUF as the main model. This PR enables loading the codec from an independent GGUF file, which is useful for:

• Modular distribution — ship codec and main model as separate downloads
• Smaller updates — update only the codec or main model independently
• Experimentation — swap codec GGUFs without repackaging the full model

Changes

File	Change
include/s2_pipeline.h	Add codec_model_path to PipelineParams
src/main.cpp	Parse --codec-model CLI argument
src/s2_codec.cpp	load_shared handles separate codec GGUF with proper metadata loading and cleanup
src/s2_pipeline.cpp	Branch codec loading when codec_model_path is set; load tensor data from separate codec file

Usage

./s2 --model main-model.gguf --codec-model codec.gguf --text "Hello world"

When --codec-model is not provided, behavior is unchanged (codec loads from the main model GGUF).

Backward compatibility

Fully backward compatible — the new flag is optional and the default behavior (codec from main GGUF) is preserved.

Summary by CodeRabbit

• New Features
  • Added support for specifying a separate codec model file via a new --codec-model <path> CLI option.
  • Pipeline now allows loading the codec from a custom model path independent of the main model, enabling flexible codec configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e76e33d-d04e-4224-9f95-44c6b24c85b4

📥 Commits

Reviewing files that changed from the base of the PR and between 2c33261 and 74af992.

📒 Files selected for processing (4)

• include/s2_pipeline.h
• src/main.cpp
• src/s2_codec.cpp
• src/s2_pipeline.cpp

---

📝 Walkthrough

Walkthrough

This pull request adds support for loading the audio codec from a separate GGUF model file. The configuration field is wired through CLI argument parsing, fallback metadata loading is added to the codec loader, and pipeline initialization is updated to use the optional separate path and load codec tensor data accordingly.

Changes

Separate Codec Model Path

Layer / File(s)	Summary
Configuration field for codec model path include/s2_pipeline.h	PipelineParams struct gains a new codec_model_path string field to hold the optional separate codec GGUF path.
CLI argument parsing for codec model path src/main.cpp	CLI help text documents --codec-model <path> option, and argument parser recognizes and stores the path in params.codec_model_path.
Codec metadata fallback in AudioCodec::load_shared src/s2_codec.cpp	AudioCodec::load_shared now validates both Model and shared_gguf_ctx up front, adds fallback logic to load GGUF metadata from gguf_path locally when shared_gguf_ctx is missing, and ensures proper cleanup of the locally opened context in error and success paths.
Pipeline codec initialization with separate path support src/s2_pipeline.cpp	Pipeline::init extends codec loading to conditionally use params.codec_model_path for GPU and CPU backends when set, and adds tensor data loading for the separate codec GGUF file alongside main model tensor loading.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A codec path springs free and bright,
No longer bound to one model's might!
Separate paths and tensor flows—
The pipeline blooms where logic grows! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change—adding support for a separate codec GGUF file via a new CLI flag—and is clear, concise, and specific.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}