audio_samples 0.10.5

A typed audio processing library for Rust that treats audio as a first-class, invariant-preserving object rather than an unstructured numeric buffer.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

# Roadmap to AudioSamples v1.0.0

The `audio_samples` crate is already functionally extensive and architecturally mature, with strong guarantees around sample typing, zero-allocation patterns, trait-based composition, and modularity. The path to **1.0.0** is therefore not about adding major new functionality, but about **stability, polish, internal coherence, and long-term API guarantees**.

Below is a focused roadmap from the current **v0.9.0** to a stable and semver-protected **v1.0.0**.

---

<!-- ## **0.9.x — Stabilisation and Internal Review**

This cycle is about tightening the internal structure without breaking public APIs prematurely.

### Goals

* Conduct a full audit of modules (`operations`, `traits`, `repr`, etc.)
* Identify naming inconsistencies, unclear method boundaries, redundant methods, or missing symmetry
* Review error variants, message consistency, and ergonomic patterns
* Confirm that trait bounds across modules reflect actual API contracts
* Internal review of iterator guarantees, window behaviour, padding semantics
* Settle final conventions for mono/multi distinction: naming, borrowing, ownership

### Expected Outputs

* A list of intended breaking changes
* A list of internal inconsistencies to be resolved
* Light refactoring that is still backward-compatible

Once this is complete, the **intended 1.0 surface is known**, even if not yet implemented.

---

## **0.10.0 — Error System Redesign**

The error layer is the weakest remaining subsystem. A complete revamp is required before 1.0.

### Goals

* Replace the current monolithic `AudioSampleError` with a **small, well-defined hierarchy**
* Enforce consistent error naming, formatting, and contextual data
* Split conversion errors, range violations, layout mismatches, and configuration errors into separate types
* Ensure operations all use the correct error types, not generic string-based variants
* Provide a stable `AudioSampleResult<T>` alias
* Achieve predictable, inspectable error behaviour across all operations

### Rationale

A clean error system is essential for ecosystem integration, especially for the CLI, Python bindings, and documentation.

--- -->

## **0.11.0 — API Consistency Pass**

This release resolves all inconsistencies identified in 0.9.x and aligns the API around a coherent design philosophy.

### Goals

* Finalise naming for:
  `as_type`, `to_type`, `cast_as`, `cast_to`, and all derived helpers
* Ensure every operation has a clear allocation policy (documented)
* Audit builder APIs (e.g., `processing()`) for consistency:
  *ordering, naming, default behaviour, error semantics*
* Harmonise mono/multi behaviour
* Ensure that trait-based operations across modules have consistent method names and signatures
* Introduce deprecation warnings for anything to be removed in 1.0

### Rationale

At this stage, the API surface is essentially frozen. All breaking changes must happen *here*.

---

## **0.12.0 — Documentation and Contracts Release**

Once the API is stable, the next step is to articulate the guarantees it provides.

### Goals

* Fully document:

  * lifetime semantics and borrowed/owned behaviour
  * allocation guarantees of every operation
  * trait designs and their precise roles
  * iterator stability and padding semantics
  * distinctions between audio-aware conversions vs. raw casting
  * invariants of `AudioSamples`, `MonoData`, `MultiData`
* Write architectural guides for:

  * trait-based operation layering
  * sample type system
  * conversion pipeline
  * processing builder
  * iterator design
* Provide “How to think about this crate” documentation
* Expand examples demonstrating the complete ecosystem

### Rationale

A 1.0 crate must be self-teaching. This release establishes the normative documentation that defines the crate’s philosophy and constraints.

---

## **0.13.0 — Performance Validation and Micro-Optimisation**

Before 1.0, the performance floor should be validated and locking in.

### Goals

* Benchmark every core operation: conversions, iterators, windows, transforms, statistics
* Validate no accidental regressions occurred during API clean-ups
* Confirm SIMD behaviour for conversion and arithmetic heavy paths
* Validate that borrowed/owned transitions do not cause accidental allocations
* Micro-optimise pathological cases identified in testing

### Rationale

Performance cannot be retrofitted after 1.0. This ensures all guarantees are real rather than implied.

---

## **0.14.0 — Final Hardening Pass**

The last pre-1.0 release. Conservative, stability-focused, with no new features.

### Goals

* Resolve all outstanding deprecations
* Run full suite of stress tests (especially windowing, STFT/ISTFT, resampling, dynamic range ops)
* Improve internal invariants checking
* Validate cross-platform behaviour
* Validate thread safety, Send/Sync guarantees

### Rationale

After this release, the API must not change in any breaking way.

---

## **1.0.0 — Stable Release**

The crate is now stable, semver-locked, and production-ready.

### Guarantees

* **Stable API surface**
* **Well-defined error system**
* **Documented allocation behaviour**
* **Zero-copy and zero-allocation guarantees where promised**
* **Consistent naming, signatures, and patterns across all operations**
* **Predictable, stable iterators and windows**
* **Robust trait boundaries and feature-gated modularity**
* **Clear and complete documentation**

### Summary

No new major features are introduced at 1.0. Instead, 1.0 marks the point at which users can depend on `audio_samples` with confidence that the design is intentional, complete, and stable.