(enhancement): SEA codec optimization by chanderlud · Pull Request #6 · chanderlud/telepathy

chanderlud · 2026-04-03T00:47:58Z

refactors the sea codec to avoid per-frame allocations
implements codec tests and benchmarks

…timization

Copilot

Pull request overview

This PR refactors the SEA audio codec implementation to reduce per-frame allocations by reusing scratch buffers across encode/decode operations, and adds integration tests + Criterion benchmarks to validate correctness and measure performance.

Changes:

Refactor SEA encoder/decoder + chunk serialization/deserialization to encode/decode into caller-provided buffers and reuse internal scratch vectors.
Update bitpacking APIs to support reuse (reset_*) and return borrowed slices from finish() to avoid allocations.
Add SEA codec integration tests and a sea_codec Criterion benchmark.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
rust/telepathy-audio/src/sea/encoder.rs	Reuses an internal `chunk_data` buffer to avoid per-frame chunk allocation.
rust/telepathy-audio/src/sea/decoder.rs	Uses `SeaFile::new_for_decoding` constructor.
rust/telepathy-audio/src/sea/codec/mod.rs	Exposes `bits` module publicly for external access (tests/benches).
rust/telepathy-audio/src/sea/codec/file.rs	Introduces reusable scratch buffers and new encode/decode-into paths.
rust/telepathy-audio/src/sea/codec/chunk.rs	Refactors chunk model into `ChunkInfo` + `serialize_into`/`parse_into` scratch-buffer APIs.
rust/telepathy-audio/src/sea/codec/encoder_cbr.rs	Moves encoding to `encode_into` and reuses scratch vectors.
rust/telepathy-audio/src/sea/codec/encoder_vbr.rs	Moves encoding to `encode_into` and reuses scratch vectors for analysis/selection.
rust/telepathy-audio/src/sea/codec/decoder.rs	Refactors decoding into `decode_*_into` and reuses internal scratch LMS.
rust/telepathy-audio/src/sea/codec/bits.rs	Adds reset methods + makes `finish()` return borrowed slices to reduce allocations.
rust/telepathy-audio/src/sea/codec/common.rs	Replaces `EncodedSamples` with `SeaEncoderTrait::encode_into` API.
rust/telepathy-audio/tests/sea_codec_test.rs	Adds round-trip tests + bitpacker/unpacker test cases.
rust/telepathy-audio/benches/sea_codec.rs	Adds Criterion benchmarks for encode/decode and bitpacking.
rust/telepathy-audio/Cargo.toml	Registers the new `sea_codec` benchmark target.
rust/telepathy_audio/tests/sea_codec_test.rs	Duplicate test file in a non-workspace directory (likely unused).
rust/telepathy_audio/benches/sea_codec.rs	Duplicate bench file in a non-workspace directory (likely unused).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

rust/telepathy-audio/src/sea/codec/chunk.rs

rust/telepathy-audio/src/sea/codec/decoder.rs

rust/telepathy-audio/src/sea/codec/file.rs

rust/telepathy-audio/src/sea/codec/encoder_vbr.rs

rust/telepathy-audio/src/sea/codec/mod.rs

rust/telepathy_audio/tests/sea_codec_test.rs

rust/telepathy_audio/benches/sea_codec.rs

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T01:39:58Z

rust/telepathy-audio/src/sea/encoder.rs

+        {
+            return Err(SeaError::InvalidParameters);
+        }
+


EncoderSettings::validate doesn't validate residual_bits even though downstream code calls SeaResidualSize::from(floor(residual_bits) as u8), which will panic for values outside 1..=8. Consider validating that residual_bits is finite and that floor(residual_bits) is within 1..=8 (and returning SeaError::InvalidParameters), so invalid settings fail gracefully instead of crashing.

Suggested change

if !self.residual_bits.is_finite()

|| !(1..=8).contains(&((self.residual_bits.floor()) as u8))

{

return Err(SeaError::InvalidParameters);

}

Copilot · 2026-04-03T01:39:58Z

rust/telepathy-audio/src/sea/codec/chunk.rs

+            for vbr_residual_size in vbr_residual_sizes.iter() {
+                let relative_size = *vbr_residual_size as i32 - residual_size as i32 + 1;


When serializing VBR residual sizes, relative_size is computed as an i32 and then cast to u32 before packing into 2 bits. If a value is outside the representable range (expected 0..=3), this will wrap/truncate in release builds (debug_asserts won’t fire) and produce an invalid stream. Please add explicit range checks for relative_size (and for vbr_residual_sizes being in 1..=8) and return SeaError::InvalidParameters on violation.

Suggested change

for vbr_residual_size in vbr_residual_sizes.iter() {

let relative_size = *vbr_residual_size as i32 - residual_size as i32 + 1;

for vbr_residual_size in vbr_residual_sizes.iter() {

if !matches!(*vbr_residual_size, 1..=8) {

return Err(SeaError::InvalidParameters);

}

let relative_size = *vbr_residual_size as i32 - residual_size as i32 + 1;

if !(0..=3).contains(&relative_size) {

return Err(SeaError::InvalidParameters);

}

Copilot · 2026-04-03T01:39:58Z

rust/telepathy-audio/src/sea/codec/chunk.rs

+            vbr_residual_sizes.extend_from_slice(unpacker.finish());
+            vbr_residual_sizes.resize(scale_factor_items, 0);
+            for item in vbr_residual_sizes.iter_mut() {
                *item += residual_size as u8 - 1;


After decoding VBR residual sizes, the code adjusts them via *item += residual_size as u8 - 1 but never validates the resulting bit-lengths. Corrupt frames can yield sizes <1 or >8 (e.g., residual_size=8 and encoded value=3 => 10), which can later panic when indexing BitUnpacker::MASKS/DQT tables. Add a validation pass here to reject any VBR residual size outside 1..=8 with SeaError::InvalidFrame.

Suggested change

*item += residual_size as u8 - 1;

let adjusted = *item + residual_size as u8 - 1;

if !(1..=8).contains(&adjusted) {

return Err(SeaError::InvalidFrame);

}

*item = adjusted;

Copilot · 2026-04-03T01:39:59Z

rust/telepathy-audio/tests/sea_codec_test.rs

+    let invalid_scale_factor_bits = [0x01_u8, 0x01, 20, 0x5A];
+
+    let res_short = decoder.decode_frame(&too_short, &mut output);
+    let res_type = decoder.decode_frame(&invalid_chunk_type, &mut output);
+    let res_sf = decoder.decode_frame(&invalid_scale_factor_bits, &mut output);
+
+    assert!(matches!(res_short, Err(SeaError::InvalidFrame)));
+    assert!(matches!(res_type, Err(SeaError::InvalidFrame)));
+    assert!(matches!(res_sf, Err(SeaError::InvalidFrame)));


invalid_frame_paths currently doesn't cover malformed VBR residual-size metadata (e.g., VBR chunk with residual_size=8 and a 2-bit residual-size code of 3 leading to an out-of-range bitlength). Adding a case here would help prevent regressions in the new scratch-buffer parsing path.

Suggested change

let invalid_scale_factor_bits = [0x01_u8, 0x01, 20, 0x5A];

let res_short = decoder.decode_frame(&too_short, &mut output);

let res_type = decoder.decode_frame(&invalid_chunk_type, &mut output);

let res_sf = decoder.decode_frame(&invalid_scale_factor_bits, &mut output);

assert!(matches!(res_short, Err(SeaError::InvalidFrame)));

assert!(matches!(res_type, Err(SeaError::InvalidFrame)));

assert!(matches!(res_sf, Err(SeaError::InvalidFrame)));

let invalid_scale_factor_bits = [0x01_u8, 0x01, 20, 0x5A];

// Malformed VBR residual-size metadata: residual_size=8 with a 2-bit

// residual-size code of 3 should be rejected instead of producing an

// out-of-range residual bitlength during parsing.

let invalid_vbr_residual_size = [0x41_u8, 0x08, 0xC0, 0x00];

let res_short = decoder.decode_frame(&too_short, &mut output);

let res_type = decoder.decode_frame(&invalid_chunk_type, &mut output);

let res_sf = decoder.decode_frame(&invalid_scale_factor_bits, &mut output);

let res_vbr_residual_size = decoder.decode_frame(&invalid_vbr_residual_size, &mut output);

assert!(matches!(res_short, Err(SeaError::InvalidFrame)));

assert!(matches!(res_type, Err(SeaError::InvalidFrame)));

assert!(matches!(res_sf, Err(SeaError::InvalidFrame)));

assert!(matches!(res_vbr_residual_size, Err(SeaError::InvalidFrame)));

chanderlud added 5 commits February 26, 2026 20:42

eliminates per-frame memory allocations in sea codec implementation

2360346

Merge branch 'master' into sea-optimization

8dc6c34

Merge remote-tracking branch 'refs/remotes/origin/master' into sea-op…

f78d18e

…timization

adds codec tests and benches

c8b8e2b

adds codec tests and benches

68e7b64

chanderlud requested a review from Copilot April 3, 2026 00:48

Copilot started reviewing on behalf of chanderlud April 3, 2026 00:48 View session

clippy and formatting

2a1900b

Copilot AI reviewed Apr 3, 2026

View reviewed changes

chanderlud added 5 commits April 2, 2026 18:05

further codec optimizations

b4b917c

improves vbr implementation for 55% speedup

ed86ff4

clamps residual bits in vbr encoder

1e3abef

clippy, invalid encoder options handling, formatting

c4ed5a1

restores the strict length check

f17ebc6

chanderlud requested a review from Copilot April 3, 2026 01:34

Copilot started reviewing on behalf of chanderlud April 3, 2026 01:35 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(enhancement): SEA codec optimization#6

(enhancement): SEA codec optimization#6
chanderlud wants to merge 11 commits intomasterfrom
sea-optimization

chanderlud commented Apr 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

+        if !self.residual_bits.is_finite()
+            || !(1..=8).contains(&((self.residual_bits.floor()) as u8))
+        {
+            return Err(SeaError::InvalidParameters);
+        }

		for vbr_residual_size in vbr_residual_sizes.iter() {
		let relative_size = *vbr_residual_size as i32 - residual_size as i32 + 1;

-                *item += residual_size as u8 - 1;
+                let adjusted = *item + residual_size as u8 - 1;
+                if !(1..=8).contains(&adjusted) {
+                    return Err(SeaError::InvalidFrame);
+                }
+                *item = adjusted;

Conversation

chanderlud commented Apr 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants