tunelet 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ByteLandTechnology
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,281 @@
1
- # Temporary Holding Version
1
+ # tunelet
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ tunelet is a Rust library for vocal pitch correction, choir, harmony,
4
+ formant control and effects. Its input is mono signed 16-bit PCM at 44.1 kHz
5
+ or 48 kHz. Its output is stereo or mono PCM. The default Rust build has no
6
+ dependencies. For `wasm32-unknown-unknown`, the optional `wasm` feature gives
7
+ JavaScript bindings and generated TypeScript declarations.
8
+
9
+ The processing chain has these stages, in this order:
10
+
11
+ 1. Punch
12
+ 2. Warm
13
+ 3. Pitch tracking, correction and voice resynthesis
14
+ 4. Alien
15
+ 5. Reverb
16
+ 6. Output gain
17
+
18
+ The default configuration enables chromatic pitch correction and uses one
19
+ choir voice. It disables the effects and the formant stage.
20
+
21
+ ## Integration
22
+
23
+ Add the repository as a Git dependency:
24
+
25
+ ```toml
26
+ [dependencies]
27
+ tunelet = { git = "https://github.com/ByteLandTechnology/tunelet.git" }
28
+ ```
29
+
30
+ To prepare a processor, do these steps:
31
+
32
+ 1. Use `SampleRate::try_from(hz)` to check the input rate.
33
+ 2. Use `PrepareConfig::new(rate, max_block_frames)` to set a nonzero block
34
+ limit.
35
+ 3. Create a `Processor` with that preparation and a `ProcessorConfig`.
36
+
37
+ Configuration structures implement `Default`. To select voices and effects,
38
+ edit their fields.
39
+
40
+ | Output layout | Function for input | Function for the tail |
41
+ | ------------------------------ | ----------------------- | --------------------- |
42
+ | `[[i16; 2]]` stereo frames | `process` | `drain` |
43
+ | Separate left and right slices | `process_planar` | `drain_planar` |
44
+ | Mono slice | `process_mono_in_place` | `drain_mono` |
45
+
46
+ Each input sample gives one output frame. The channel lengths must be equal,
47
+ and each call must fit in the prepared block limit. Short blocks and empty
48
+ blocks are permitted. All operations that can fail do their validation before
49
+ they change the state or the output.
50
+
51
+ To apply controls immediately before specific frames, give `TimedEvent`
52
+ values. These rules apply to the offsets:
53
+
54
+ - Offsets start at zero in each block.
55
+ - Each offset must be in the block.
56
+ - An offset must not be less than the offset before it.
57
+
58
+ Events with equal offsets execute in slice order. An empty block accepts no
59
+ events. Harmony MIDI uses `ControlEvent::Midi`. MIDI for the correction
60
+ keyboard uses `ControlEvent::CorrectionMidi`.
61
+
62
+ ## State and timing
63
+
64
+ Construction allocates the storage of the processor. These operations do not
65
+ allocate memory, acquire locks or do I/O:
66
+
67
+ - Processing
68
+ - Configuration
69
+ - MIDI
70
+ - Feedback
71
+ - Reset
72
+ - Drain
73
+
74
+ The crate forbids unsafe Rust.
75
+
76
+ To get the tail after the last input block, do these steps:
77
+
78
+ 1. Call `begin_drain()` one time.
79
+ 2. From each drain call, use only the frames that the call returns.
80
+
81
+ The drain fills the unused output with zeros. The drain has a finite budget,
82
+ which can include silence. Completion resets the audio histories and the
83
+ feedback. A successful call that processes audio or sets the configuration
84
+ cancels the drain. `reset()` also cancels the drain.
85
+
86
+ `feedback()` reads the pitch information, the stereo peak, the correction
87
+ ratio, the frame count and the latency. `take_feedback()` also clears the
88
+ peak window. `latency_frames()` gives 1,593 frames of nominal resynthesis
89
+ latency at both sample rates. Dry mixes, resampled voices and effects have
90
+ different timing.
91
+
92
+ `reset()` keeps the configuration, the random stream and some controller and
93
+ filter state. If you need a fully new state, construct a new processor.
94
+
95
+ The API documentation gives the parameter ranges, the MIDI behavior and the
96
+ reset semantics. To open it, run this command:
97
+
98
+ ```sh
99
+ cargo doc --locked --no-deps --open
100
+ ```
101
+
102
+ ## Build
103
+
104
+ To build the crate and check the format and the lints, run these commands:
105
+
106
+ ```sh
107
+ cargo build --locked --release
108
+ cargo fmt --check
109
+ cargo clippy --locked --lib -- -D warnings
110
+ ```
111
+
112
+ ## WebAssembly and TypeScript
113
+
114
+ The npm package is one ES module for both browsers and Node.js. It contains
115
+ these items:
116
+
117
+ - One Wasm binary.
118
+ - The generated bindings.
119
+ - A shared `loadTunelet` entry point.
120
+
121
+ Both environments use the same imports and the same initialization call:
122
+
123
+ ```ts
124
+ import { loadTunelet, Tunelet, defaultConfig } from "tunelet";
125
+
126
+ await loadTunelet();
127
+ const config = defaultConfig();
128
+ config.resynthesis.pitchRatio = 1.25;
129
+ const processor = new Tunelet(48000, 1024, config);
130
+
131
+ const input = new Int16Array(1024);
132
+ const left = new Int16Array(1024);
133
+ const right = new Int16Array(1024);
134
+ // Fill input with mono PCM before each call; reuse all three arrays.
135
+ processor.process(input, left, right);
136
+
137
+ // After all processing and optional drain calls:
138
+ processor.free();
139
+ ```
140
+
141
+ Node.js reads the packaged binary from a file URL relative to the module.
142
+ Browsers fetch the served Wasm asset. An import of the package does not load
143
+ the binary. Call `loadTunelet()` before you use `Tunelet` or `defaultConfig()`.
144
+
145
+ Concurrent calls share one initialization promise. The package keeps the
146
+ result of a successful initialization. If a load fails, the promise rejects,
147
+ and you can try again. A Node.js file error goes to the caller.
148
+
149
+ For a custom asset location, give one of these sources to
150
+ `loadTunelet(source)`:
151
+
152
+ - A URL.
153
+ - A fetch Response.
154
+ - A byte buffer.
155
+ - A compiled `WebAssembly.Module`.
156
+ - A promise for one of these.
157
+
158
+ For a Node.js `file:` source, use a URL object. A string source obeys fetch
159
+ rules. The first concurrent call selects the source. Later arguments do not
160
+ replace an initialized module. A custom binary must match the generated
161
+ bindings.
162
+
163
+ The package root also exports `loadTunelet` as its default export. For direct
164
+ control of Wasm initialization, `tunelet/wasm` gives the generated default
165
+ initializer and `initSync`. The package root re-exports `initSync` too. Use
166
+ only one initialization entry point for each module instance. The package
167
+ gives only ESM exports. CommonJS applications can use `await import("tunelet")`.
168
+
169
+ Browser bundlers must keep or emit the Wasm asset that
170
+ `new URL(..., import.meta.url)` refers to. For a browser deployment without a
171
+ bundler, do these steps:
172
+
173
+ 1. Serve `dist/` and `pkg/`, and keep their relative layout.
174
+ 2. Map the `tunelet` import to `dist/index.js`, or import that URL directly.
175
+
176
+ Serve the assets over HTTP(S). The package does not support a local `file:`
177
+ page that opens the JavaScript.
178
+
179
+ ### Build the shared package
180
+
181
+ Install Node.js and `wasm-pack`. Then run these commands to add the
182
+ `wasm32-unknown-unknown` Rust target, install the development dependencies
183
+ and make the archive:
184
+
185
+ ```sh
186
+ rustup target add wasm32-unknown-unknown
187
+ npm ci
188
+ npm pack
189
+ ```
190
+
191
+ `npm pack` builds the Wasm bindings and the TypeScript entry point. Then it
192
+ creates `tunelet-0.1.1.tgz`. To use this archive in a browser project or a
193
+ Node.js project, install it with `npm install /path/to/tunelet-0.1.1.tgz`. For
194
+ local use, it is not necessary to publish the package to npm. To build without
195
+ an archive, run `npm run build`.
196
+
197
+ The build writes one `web`-target binding into `pkg/` and the shared entry
198
+ into `dist/`. Git ignores both directories. The archive contains only these
199
+ items:
200
+
201
+ - The runtime entry.
202
+ - The declarations.
203
+ - The bindings.
204
+ - The binary.
205
+ - The package metadata.
206
+ - The README.
207
+
208
+ The `build:wasm` script uses `--no-opt`. This flag disables the separate
209
+ Binaryen pass, but Rust still builds in release mode. The TypeScript and
210
+ Node.js type declarations are only development dependencies. Native Rust
211
+ builds use Cargo and do not need Node.js or npm.
212
+
213
+ | Operation | TypeScript API |
214
+ | --------------------------------- | -------------------------------------------------------- |
215
+ | Shared initialization | `loadTunelet(source?)` |
216
+ | Mono PCM to planar stereo | `process(input, left, right, events?)` |
217
+ | In-place mono downmix | `processMono(audio, events?)` |
218
+ | Configuration | `config()`, `setConfig(config)`, `defaultConfig()` |
219
+ | Information about the preparation | `sampleRate`, `maxBlockFrames`, `latencyFrames` |
220
+ | Feedback | `feedback()`, `takeFeedback()` |
221
+ | Finite tail | `beginDrain()`, `drain(left, right)`, `drainMono(audio)` |
222
+ | Configured tail budget | `tailFrames()` |
223
+ | Reset or release memory | `reset()`, `free()` |
224
+
225
+ All audio buffers are `Int16Array` buffers, and they must fit in the prepared
226
+ frame limit. Stereo output arrays must not overlap. The input can overlap an
227
+ output, because the binding copies the input first. Buffers must stay attached
228
+ during each call. Web Audio uses Float32 samples, which you must convert to
229
+ and from 16-bit PCM. This package does not install an AudioWorklet or an
230
+ integration with an audio device.
231
+
232
+ Configuration objects contain all fields. They use camelCase names and show
233
+ enums as string literals. To change the configuration, do these steps:
234
+
235
+ 1. Start from `defaultConfig()` or `config()`.
236
+ 2. Edit the necessary fields.
237
+ 3. Call `setConfig()`.
238
+
239
+ If a field is missing or a value is not valid, the call throws a JavaScript
240
+ `Error`. The conversion ignores extra object properties. The generated
241
+ declarations contain the parameter documentation from the Rust types.
242
+ `resynthesis.randomSeed` and the `processedFrames` field of feedback use
243
+ `bigint`. Frame offsets, block lengths and latency use `number`.
244
+
245
+ In feedback, `targetMidiNote` is `undefined` in these cases, which are also
246
+ the cases where `voiced` is `false`:
247
+
248
+ - The kept pitch estimate is unvoiced. This includes the time before the
249
+ first detection and after a reset or a drain completion.
250
+ - The estimated frequency is outside the inclusive reporting bounds
251
+ `resynthesis.pitch.minFrequencyHz` and `resynthesis.pitch.maxFrequencyHz`.
252
+
253
+ The optional event argument is a `TimedEvent[]`. Controls use a `type`
254
+ discriminant and a `value` payload. The reset control has no payload. For
255
+ example, `{ offset: 0, event: { type: "outputGain", value: 0.5 } }` changes
256
+ the final gain before the first frame.
257
+
258
+ A harmony Note On event uses
259
+ `{ offset: 0, event: { type: "midi", value: { type: "noteOn", channel: 0, note: 60, velocity: 100 } } }`.
260
+ Use `correctionMidi` for the separate correction keyboard. The native rules
261
+ for event order and for the validation of the whole block also apply to these
262
+ bindings.
263
+
264
+ The constructor allocates reusable PCM buffers. A successful call that
265
+ processes audio without events does not allocate new Rust PCM storage.
266
+ However, the call copies the audio across the boundary between JavaScript and
267
+ Wasm. These items can allocate:
268
+
269
+ - Object conversion.
270
+ - Supplied events.
271
+ - Errors.
272
+ - Feedback.
273
+
274
+ The generated glue can also make temporary views. This binding is for general
275
+ use, and it does not guarantee hard real-time behavior for allocation or
276
+ scheduling. Drain completion and reset keep the same state as the equivalent
277
+ Rust functions.
278
+
279
+ ## License
280
+
281
+ tunelet is available under the MIT License. Refer to [LICENSE](LICENSE).
@@ -0,0 +1,37 @@
1
+ import type { InitInput, InitOutput } from "../pkg/tunelet.js";
2
+ export * from "../pkg/tunelet.js";
3
+ /**
4
+ * Initializes the Wasm module one time for this imported package instance.
5
+ *
6
+ * If you give no argument, the function finds the packaged binary relative to
7
+ * this module. Node.js reads a `file:` URL, and browsers fetch the served
8
+ * asset. An import of the package does not load Wasm. In browsers, serve the
9
+ * assets over HTTP(S), or give the bytes or a compiled module as the source.
10
+ *
11
+ * For a custom deployment, you can give one of these sources:
12
+ *
13
+ * - A URL.
14
+ * - A fetch Response.
15
+ * - A byte buffer (BufferSource).
16
+ * - A compiled WebAssembly.Module.
17
+ * - A promise for one of these.
18
+ *
19
+ * A string source obeys fetch rules. For a Node.js `file:` source, use a
20
+ * URL object. A compiled module must use imports that agree with the packaged
21
+ * bindings.
22
+ *
23
+ * Concurrent calls share one promise, and the first call selects the source.
24
+ * After a successful initialization, later calls use it again and do not load
25
+ * Wasm again, whatever their arguments are. If an attempt fails, the promise
26
+ * rejects and the function clears the cached promise. Then you can try again.
27
+ * File, network and Wasm errors go to the caller. The function does not try a
28
+ * different load method after an error.
29
+ *
30
+ * @param source The optional Wasm source. The default is the binary in this
31
+ * package.
32
+ * @returns The initialized Wasm exports. Use the re-exported `Tunelet` class
33
+ * for processors.
34
+ */
35
+ export declare function loadTunelet(source?: InitInput | Promise<InitInput>): Promise<InitOutput>;
36
+ /** The default export is the same function as `loadTunelet`. */
37
+ export default loadTunelet;
package/dist/index.js ADDED
@@ -0,0 +1,70 @@
1
+ /**
2
+ * The shared ESM entry point for browsers and Node.js.
3
+ *
4
+ * Call `loadTunelet()` before you construct processors or read the default
5
+ * configuration. Both environments use the same generated bindings and the
6
+ * same Wasm binary. This module re-exports all named exports of the module
7
+ * that wasm-bindgen generates, which include `Tunelet`, `defaultConfig`,
8
+ * `initSync` and the configuration, event and feedback types.
9
+ */
10
+ import init, { initSync } from "../pkg/tunelet.js";
11
+ export * from "../pkg/tunelet.js";
12
+ /** The shared initialization promise, which a failure clears. */
13
+ let initialization;
14
+ /**
15
+ * Initializes the Wasm module one time for this imported package instance.
16
+ *
17
+ * If you give no argument, the function finds the packaged binary relative to
18
+ * this module. Node.js reads a `file:` URL, and browsers fetch the served
19
+ * asset. An import of the package does not load Wasm. In browsers, serve the
20
+ * assets over HTTP(S), or give the bytes or a compiled module as the source.
21
+ *
22
+ * For a custom deployment, you can give one of these sources:
23
+ *
24
+ * - A URL.
25
+ * - A fetch Response.
26
+ * - A byte buffer (BufferSource).
27
+ * - A compiled WebAssembly.Module.
28
+ * - A promise for one of these.
29
+ *
30
+ * A string source obeys fetch rules. For a Node.js `file:` source, use a
31
+ * URL object. A compiled module must use imports that agree with the packaged
32
+ * bindings.
33
+ *
34
+ * Concurrent calls share one promise, and the first call selects the source.
35
+ * After a successful initialization, later calls use it again and do not load
36
+ * Wasm again, whatever their arguments are. If an attempt fails, the promise
37
+ * rejects and the function clears the cached promise. Then you can try again.
38
+ * File, network and Wasm errors go to the caller. The function does not try a
39
+ * different load method after an error.
40
+ *
41
+ * @param source The optional Wasm source. The default is the binary in this
42
+ * package.
43
+ * @returns The initialized Wasm exports. Use the re-exported `Tunelet` class
44
+ * for processors.
45
+ */
46
+ export function loadTunelet(source) {
47
+ initialization ?? (initialization = initialize(source).catch((error) => {
48
+ initialization = undefined;
49
+ throw error;
50
+ }));
51
+ return initialization;
52
+ }
53
+ /** Awaits the source one time, then initializes the Wasm module from it. */
54
+ async function initialize(source) {
55
+ const input = source === undefined
56
+ ? new URL("../pkg/tunelet_bg.wasm", import.meta.url)
57
+ : await source;
58
+ if (input instanceof URL && input.protocol === "file:") {
59
+ // Keep the Node.js built-in module out of browser bundles. TypeScript
60
+ // removes the type-only import. The runtime import runs only for `file:`
61
+ // URLs.
62
+ const moduleName = "node:fs/promises";
63
+ const fs = await import(
64
+ /* webpackIgnore: true */ /* @vite-ignore */ moduleName);
65
+ return initSync({ module: await fs.readFile(input) });
66
+ }
67
+ return init({ module_or_path: input });
68
+ }
69
+ /** The default export is the same function as `loadTunelet`. */
70
+ export default loadTunelet;
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "tunelet",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Vocal pitch correction, choir, harmony, formant control and effects for WebAssembly",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/ByteLandTechnology/tunelet.git"
9
+ },
10
+ "type": "module",
11
+ "main": "./dist/index.js",
12
+ "types": "./dist/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "import": "./dist/index.js"
17
+ },
18
+ "./wasm": {
19
+ "types": "./pkg/tunelet.d.ts",
20
+ "import": "./pkg/tunelet.js"
21
+ }
22
+ },
23
+ "files": [
24
+ "dist",
25
+ "pkg/tunelet.js",
26
+ "pkg/tunelet.d.ts",
27
+ "pkg/tunelet_bg.wasm"
28
+ ],
29
+ "sideEffects": false,
30
+ "scripts": {
31
+ "build": "npm run build:wasm && npm run build:ts",
32
+ "build:wasm": "wasm-pack build --target web --out-dir pkg --release --no-opt --features wasm --locked",
33
+ "build:ts": "tsc",
34
+ "prepack": "npm run build"
35
+ },
36
+ "devDependencies": {
37
+ "@types/node": "^22.20.5",
38
+ "typescript": "^7.0.2"
39
+ }
40
+ }