Debian Codegraph @

wasm/browser/index.d.ts

raw
1 import EventEmitter from "eventemitter3";
2
3 declare interface CsoundFs {
4 appendFile: (path: string, file: Uint8Array) => Promise<void>;
5 writeFile: (path: string, file: Uint8Array) => Promise<void>;
6 readFile: (path: string) => Promise<Uint8Array>;
7 unlink: (path: string) => Promise<void>;
8 readdir: (path: string) => Promise<string[]>;
9 mkdir: (path: string) => Promise<void>;
10 }
11
12 /**
13 * @property "play" - called anytime performance goes from pause/stop to a running state.
14 * @property "pause" - called after any successful csound.pause() calls.
15 * @property "stop" - called after end of performance or after a successful csound.stop().
16 * @property "realtimePerformanceStarted" - called at the start of realtime performance but not on resume or render.
17 * @property "realtimePerformancePaused" - only called if csound.pause() was successfully called during performance.
18 * @property "realtimePerformanceResumed" - only called if csound.resume() was successfully called after a pause.
19 * @property "realtimePerformanceEnded" - called after end of performance or after a successful csound.stop().
20 * @property "renderStarted" - called at the start of offline/non-realtime render to disk.
21 * @property "renderEnded" - called at the end of offline/non-realtime render to disk.
22 * @property "onAudioNodeCreated" - called when an audioNode is created from the AudioContext before realtime performance.
23 * the event callback will include the audioNode itself, which is needed if autoConnect is set to false.
24 * @property "message" - the main entrypoint to csound's messaging (-m) system,
25 * a default event listener will print the message to the browser console, this default
26 * listener can be removed by the user.
27 */
28 declare type PublicEvents =
29 | "play"
30 | "pause"
31 | "stop"
32 | "realtimePerformanceStarted"
33 | "realtimePerformancePaused"
34 | "realtimePerformanceResumed"
35 | "realtimePerformanceEnded"
36 | "renderStarted"
37 | "renderEnded"
38 | "onAudioNodeCreated"
39 | "message";
40
41 /**
42 * CsoundObj API.
43 */
44 declare interface CsoundObj {
45 /** Returns the AudioContext used to create AudioNodes. May be one passed as initialization parameters to
46 * Csound() or one created by Csound itself if none are provided.
47 */
48 getAudioContext: () => Promise<AudioContext | undefined>;
49
50 /** Returns the AudioNode used with Csound processing. May return undefined if node has not yet been created.
51 * Single-thread (the default) backends will have nodes available right after initializing Csound, while worker-backed
52 * versions of Csound may construct the node later when Csound starts.
53 */
54 getNode: () => Promise<AudioNode | undefined>;
55
56 /**
57 * Returns an array listing the events for which the emitter has registered listeners.
58 * The values in the array are strings.
59 */
60 eventNames: () => string[];
61 /**
62 * Returns the number of listeners listening to the event named eventName.
63 */
64 listenerCount: () => number;
65 /**
66 * Returns a copy of the array of listeners for the event named eventName.
67 */
68 listeners: (eventName: PublicEvents) => Array<EventEmitter.EventListener<PublicEvents, any>>;
69 /**
70 * Alias for removeListener()
71 */
72 off: (
73 eventName: PublicEvents,
74 listener: EventEmitter.EventListener<PublicEvents, any>,
75 ) => EventEmitter;
76 /**
77 * Adds the listener to the end of the listeners array for the event named eventName.
78 * No checks are made to see if the listener has already been added.
79 * Multiple calls passing the same combination of eventName and listener
80 * will result in the listener being added, and called, multiple times.
81 */
82 on: (
83 eventName: PublicEvents,
84 listener: EventEmitter.EventListener<PublicEvents, any>,
85 ) => EventEmitter;
86 /**
87 * Alias for "on"
88 */
89 addListener: (
90 eventName: PublicEvents,
91 listener: EventEmitter.EventListener<PublicEvents, any>,
92 ) => EventEmitter;
93 /**
94 * Adds a one-time listener for the event named eventName.
95 * The next time eventName is triggered, this listener is removed and then invoked.
96 */
97 once: (
98 eventName: PublicEvents,
99 listener: EventEmitter.EventListener<PublicEvents, any>,
100 ) => EventEmitter;
101 /**
102 * Removes all listeners, or those of the specified eventName.
103 * It is bad practice to remove listeners added elsewhere in the code,
104 * particularly when the EventEmitter instance was created by some other
105 * component or module.
106 * Returns a reference to the EventEmitter, so that calls can be chained.
107 */
108 removeAllListeners: (eventName: PublicEvents) => EventEmitter;
109 /**
110 * Removes the specified listener from the listener array for the event named eventName.
111 */
112 removeListener: (
113 eventName: PublicEvents,
114 listener: EventEmitter.EventListener<PublicEvents, any>,
115 ) => EventEmitter;
116 /**
117 * CsoundFilesystem
118 */
119 fs: CsoundFs;
120 /**
121 * Returns the sample rate from Csound instance
122 */
123 getSr: () => Promise<number>;
124 /**
125 * Returns the control rate from Csound instance
126 */
127 getKr: () => Promise<number>;
128 /**
129 * Returns the ksmps value (kr/sr) from Csound instance
130 */
131 getKsmps: () => Promise<number>;
132 /**
133 * Returns the number of output channels from Csound instance
134 */
135 getNchnls: () => Promise<number>;
136 /**
137 * Returns the number of input channels from Csound instance
138 */
139 getNchnlsInput: () => Promise<number>;
140 /**
141 * Returns the value of csoundGet0dBFS
142 */
143 get0dBFS: () => Promise<number>;
144 /**
145 * Returns the A4 frequency reference
146 */
147 getA4: () => Promise<number>;
148 /**
149 * Return the current performance time in samples
150 */
151 getCurrentTimeSamples: () => Promise<number>;
152 /**
153 * Return the size of MYFLT in number of bytes
154 */
155 getSizeOfMYFLT: () => Promise<number>;
156 /**
157 * Set a single csound option (flag),
158 * no spaces are allowed in the string.
159 */
160 setOption: (option: string) => Promise<number>;
161 /**
162 * Configure Csound with a given set of
163 * parameters defined in the CSOUND_PARAMS structure.
164 * These parameters are the part of the OPARMS struct
165 * that are configurable through command line flags.
166 * The CSOUND_PARAMS structure can be obtained using
167 * csoundGetParams().
168 * These options should only be changed before
169 * performance has started.
170 * @param csoundParams - csoundParams object
171 */
172 setParams: (csoundParams: CSOUND_PARAMS) => Promise<undefined>;
173 /**
174 * Get the current set of parameters
175 * from a Csound instance
176 * in a CSOUND_PARAMS structure.
177 * @returns - CSOUND_PARAMS object
178 */
179 getParams: () => Promise<CSOUND_PARAMS>;
180 /**
181 * Returns whether Csound is set to print debug messages
182 * sent through the DebugMsg() internal API function.
183 * Anything different to 0 means true.
184 */
185 getDebug: () => Promise<number>;
186 /**
187 * Return the size of MYFLT in number of bytes
188 */
189 setDebug: (debug: number) => Promise<undefined>;
190 /**
191 * Inputs an immediate score event
192 * without any pre-process parsing
193 */
194 inputMessage: (scoreEvent: string) => Promise<number>;
195 /**
196 * Inputs an immediate score event
197 * without any pre-process parsing
198 */
199 inputMessageAsync: (scoreEvent: string) => Promise<number>;
200 /**
201 * Retrieves the value of control channel identified by channelName.
202 * If the err argument is not NULL, the error (or success) code finding
203 * or accessing the channel is stored in it.
204 */
205 getControlChannel: (channelName: string) => Promise<undefined>;
206 /**
207 * Sets the value of control channel identified by channelName
208 */
209 setControlChannel: (channelName: string, value: number) => Promise<undefined>;
210 /**
211 * Retrieves the string channel identified by channelName
212 */
213 getStringChannel: (channelName: string) => Promise<undefined>;
214 /**
215 * Sets the string channel value identified by channelName
216 */
217 setStringChannel: (channelName: string, value: string) => Promise<undefined>;
218 /**
219 * Returns the audio output name (-o)
220 */
221 getOutputName: () => Promise<string>;
222 /**
223 * Returns the audio input name (-i)
224 */
225 getInputName: () => Promise<string>;
226 /**
227 * Destroys an instance of Csound and frees memory
228 */
229 destroy: () => Promise<undefined>;
230 /**
231 * Returns the API version as int
232 */
233 getAPIVersion: () => Promise<number>;
234 /**
235 * Returns the Csound version as int
236 */
237 getVersion: () => Promise<number>;
238 /**
239 * Initialise Csound with specific flags.
240 * This is called internally by csoundCreate(),
241 * so there is generally no need to use it explicitly
242 * unless you need to avoid default initilization that
243 * sets signal handlers and atexit() callbacks.
244 * @returns - Return value is zero on success,
245 * positive if initialisation was done already, and negative on error.
246 */
247 initialize: () => Promise<number>;
248 /**
249 * Parses a csound orchestra string
250 */
251 parseOrc: (orc: string) => Promise<object>;
252 /**
253 * Compiles AST tree
254 */
255 compileTree: (tree: any) => Promise<number>;
256 /**
257 * Compiles a csound orchestra string
258 */
259 compileOrc: (orc: string) => Promise<number>;
260 /**
261 * Compiles a csound orchestra string
262 */
263 evalCode: (orc: string) => Promise<number>;
264 /**
265 * Prepares Csound for performance
266 */
267 start: () => Promise<number>;
268 /**
269 * Compiles a Csound input file but does not perform it.
270 */
271 compileCsd: (path: string) => Promise<number>;
272 /**
273 * Compiles a CSD string but does not perform it.
274 */
275 compileCsdText: (orc: string) => Promise<number>;
276 /**
277 * Pauses a performance if it's running
278 */
279 pause: () => Promise<undefined>;
280 /**
281 * Resumes a performance if it's paused
282 */
283 resume: () => Promise<undefined>;
284 /**
285 * Performs(plays) audio until end is reached
286 */
287 perform: () => Promise<number>;
288 /**
289 * Performs(plays) 1 ksmps worth of sample(s)
290 */
291 performKsmps: () => Promise<number>;
292 /**
293 * Performs(plays) 1 buffer worth of audio
294 */
295 performBuffer: () => Promise<number>;
296 /**
297 * Stops a csoundPerform
298 */
299 stop: () => Promise<undefined>;
300 /**
301 * Prints information about the end of a performance,
302 * and closes audio and MIDI devices.
303 */
304 cleanup: () => Promise<number>;
305 /**
306 * Prints information about the end of a performance,
307 * and closes audio and MIDI devices.
308 */
309 reset: () => Promise<number>;
310 /**
311 * Returns the number of samples in Csound's input buffer.
312 */
313 getInputBufferSize: () => Promise<number>;
314 /**
315 * Returns the number of samples in Csound's output buffer.
316 */
317 getOutputBufferSize: () => Promise<number>;
318 /**
319 * Returns the address of the Csound audio input buffer.
320 */
321 getInputBuffer: () => Promise<number>;
322 /**
323 * Returns the address of the Csound audio output buffer.
324 */
325 getOutputBuffer: () => Promise<number>;
326 /**
327 * Returns the address of the Csound audio input working buffer (spin).
328 * Enables external software to write audio into Csound before calling csoundPerformKsmps.
329 */
330 getSpin: () => Promise<number>;
331 /**
332 * Returns the address of the Csound audio output working buffer (spout).
333 * Enables external software to read audio from Csound after calling csoundPerformKsmps.
334 */
335 getSpout: () => Promise<number>;
336 /**
337 * Sees whether Csound score events are performed or not,
338 * independently of real-time MIDI events
339 */
340 isScorePending: () => Promise<number>;
341 /**
342 * Sets whether Csound score events are performed or not
343 * (real-time events will continue to be performed).
344 * Can be used by external software, such as a VST host,
345 * to turn off performance of score events (while continuing to perform real-time events),
346 * for example to mute a Csound score while working on other tracks of a piece,
347 * or to play the Csound instruments live.
348 */
349 setScorePending: (pending: number) => Promise<undefined>;
350 /**
351 * Read, preprocess, and load a score from an ASCII string It can be called repeatedly,
352 * with the new score events being added to the currently scheduled ones.
353 */
354 readScore: (score: string) => Promise<undefined>;
355 /**
356 * Returns the current score time in seconds since the beginning of performance.
357 */
358 getScoreTime: () => Promise<number>;
359 /**
360 * Returns the score time beginning at which score events will actually immediately be performed
361 */
362 getScoreOffsetSeconds: () => Promise<number>;
363 /**
364 * Csound score events prior to the specified time are not performed,
365 * and performance begins immediately at the specified time
366 * (real-time events will continue to be performed as they are received).
367 * Can be used by external software, such as a VST host, to begin
368 * score performance midway through a Csound score,
369 * for example to repeat a loop in a sequencer,
370 * or to synchronize other events with the Csound score.
371 */
372 setScoreOffsetSeconds: (time: number) => Promise<number>;
373 /**
374 * Rewinds a compiled Csound score to the time specified with csoundObj.setScoreOffsetSeconds().
375 */
376 rewindScore: () => Promise<number>;
377 /**
378 * Returns the length of a table
379 * (not including the guard point),
380 * or -1 if the table does not exist.
381 */
382 tableLength: (tableNum: string) => Promise<number>;
383 /**
384 * Returns the value of a slot in a table.
385 * The table number and index are assumed to be valid.
386 */
387 tableGet: (tableNum: string, tableIndex: string) => Promise<number>;
388 /**
389 * Sets the value of a slot in a table.
390 * The table number and index are assumed to be valid.
391 */
392 tableSet: (tableNum: string, tableIndex: string, value: string) => Promise<undefined>;
393 /**
394 * Copy the contents of an Array or TypedArray from javascript into a given csound table.
395 * The table number is assumed to be valid, and the table needs to have sufficient space
396 * to receive all the array contents.
397 */
398 tableCopyIn: (tableNum: string, array: number[] | ArrayLike<number>) => Promise<undefined>;
399 /**
400 * Copies the contents of a table from csound into Float64Array.
401 * The returns a Float64Array if the table exists, otherwise
402 * it returns undefined.
403 */
404 tableCopyOut: (tableNum: string) => Promise<Float64Array | undefined>;
405 getTable: (tableNum: string) => Promise<Float64Array | undefined>;
406 /**
407 * Copies the contents of a table from csound into Float64Array.
408 * The returns a Float64Array if the table exists, otherwise
409 * it returns undefined.
410 */
411 getTableArgs: (tableNum: string) => Promise<Float64Array | undefined>;
412 /**
413 * Checks if a given GEN number num is a named GEN if so,
414 * it returns the string length (excluding terminating NULL char).
415 * Otherwise it returns 0.
416 */
417 isNamedGEN: (tableNum: string) => Promise<number>;
418 /**
419 * Gets the GEN name from a number num, if this is a named GEN.
420 * If the table number doesn't represent a named GEN, it will
421 * return undefined.
422 */
423 getNamedGEN: (tableNum: string) => Promise<string | undefined>;
424 /**
425 * Emit a midi message
426 */
427 midiMessage: (status: number, data1: number, data2: number) => Promise<undefined>;
428 /**
429 * Terminates an instances and all its workers, making disabling any futher uses of a given instance.
430 */
431 terminateInstance: () => Promise<void>;
432 }
433
434 /**
435 * The default entry for @csound/wasm/browser module.
436 * If loaded successfully, it returns CsoundObj,
437 * otherwise undefined.
438 * @param [params] - Initialization parameters
439 * @param [params.audioContext] - Optional AudioContext to use; if none given, an AudioContext will be created.
440 * @param [params.inputChannelCount] - Optional input channel count for AudioNode used with WebAudio graph.
441 * Defaults to the value of nchnls_i in useWorker but 2 otherwise.
442 * @param [params.outputChannelCount] - Optional output channel count AudioNode used with WebAudio graph.
443 * Defaults to the value of nchnls in useWorker but 2 otherwise.
444 * @param [params.autoConnect = true] - Set to configure Csound to automatically connect to the audioContext.destination output.
445 * @param [params.withPlugins] - Array of WebAssembly Csound plugin libraries to use with Csound.
446 * @param [params.useWorker = false] - Configure to use backend using Web Workers to run Csound in a thread separate from audio callback.
447 * @param [params.useSAB = true] - Configure to use SharedArrayBuffers for WebWorker communications if platform supports it.
448 * @param [params.useSPN = false] - Configure to use explicitly request ScriptProcessorNode rather than AudioWorklet. Recommended only for debug testing purposes.
449 */
450 declare function Csound(params?: {
451 audioContext?: AudioContext;
452 inputChannelCount?: number;
453 outputChannelCount?: number;
454 autoConnect?: boolean;
455 withPlugins?: object[];
456 useWorker?: boolean;
457 useSAB?: boolean;
458 useSPN?: boolean;
459 }): Promise<CsoundObj | undefined>;
460
461 declare type Csound = typeof Csound;
462
463 declare type CSOUND_PARAMS = {
464 debug_mode: number;
465 buffer_frames: number;
466 hardware_buffer_frames: number;
467 displays: number;
468 ascii_graphs: number;
469 postscript_graphs: number;
470 message_level: number;
471 tempo: number;
472 ring_bell: number;
473 use_cscore: number;
474 terminate_on_midi: number;
475 heartbeat: number;
476 defer_gen01_load: number;
477 midi_key: number;
478 midi_key_cps: number;
479 midi_key_oct: number;
480 midi_key_pch: number;
481 midi_velocity: number;
482 };