Skip to content

Commit

Permalink
final webchuck version documentation prep
Browse files Browse the repository at this point in the history
  • Loading branch information
@terryzfeng
terryzfeng committed Oct 24, 2024
1 parent 0919c85 commit 5237e23
Show file tree
Hide file tree
Showing 20 changed files with 579 additions and 404 deletions.
58 changes: 42 additions & 16 deletions dist/Chuck.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,34 @@
import type { Filename } from "./utils";
/**
* WebChucK extends the Web Audio `AudioWorkletNode` and provides an interface
* to interact with the ChucK Virtual Machine.
* WebChucK extends the Web Audio `AudioWorkletNode` class and provides an
* interface to interact with the ChucK Virtual Machine. Use
* **{@link init | init()}** to create a ChucK instance.
*
* Get started with **{@link init | init()}** to create a ChucK instance.
* `theChuck` is a global variable that is used in the examples below. `init()`
* will create a ChucK instance and an AudioContext if one is not provided.
*
* ```ts
* import { Chuck } from "webchuck";
*
* let theChuck; // global variable
*
* document.getElementById("start").addEventListener("click", async () => {
* if (theChuck === undefined) {
* theChuck = await Chuck.init([]);
* }
* theChuck.runCode("SinOsc osc => dac; 1::second => now;");
* });
* ```
*
* Note that many browsers do not let audio run until there has been user
* interaction (e.g. button press). You can check for a suspended audio context
* and resume like this:
*
* ```ts
* if (theChuck.context.state === "suspended") {
* theChuck.context.resume();
* }
* ```
*/
export default class Chuck extends window.AudioWorkletNode {
private deferredPromises;
Expand All @@ -30,7 +55,7 @@ export default class Chuck extends window.AudioWorkletNode {
* Initialize a ChucK AudioWorkletNode. By default, a new AudioContext is
* created and ChucK is connected to the AudioContext destination.
* **Note:** init() is overloaded to allow for a custom AudioContext,
* custom number of output channels, and custom location of `whereIsChuck`.
* custom number of output channels, and custom URL location of `whereIsChuck`.
* Skip an argument by passing in `undefined`.
*
* @example
Expand Down Expand Up @@ -92,15 +117,16 @@ export default class Chuck extends window.AudioWorkletNode {
* ```ts
* theChuck.loadFile("./myFile.ck");
* ```
* @param url path or url to a file to fetch and load file
* @param url Path or url to a file to fetch and load file
* @returns Promise of fetch request
*/
loadFile(url: string): Promise<void>;
/**
* Load a single WebChugin (.chug.wasm) via url into WebChucK.
* A list of publicly available WebChugins to load can be found in the {@link https://chuck.stanford.edu/chugins/ | webchugins} folder.
* A list of publicly available WebChugins to load can be found in the {@link https://ccrma.stanford.edu/~tzfeng/static/webchugins/ | webchugins} folder.
* Call this per chugin that you want to load.
* **Note:** WebChugins must be loaded before `theChuck` is initialized.
* @param url url to webchugin to load
* @param url URL to webchugin to load
* @example
* ```ts
* Chuck.loadChugin("https://url/to/myChugin.chug.wasm");
Expand Down Expand Up @@ -183,7 +209,7 @@ export default class Chuck extends window.AudioWorkletNode {
* e.g. Thie is the chuck command line equivalent of `chuck myFile:1:2:foo`
* @example theChuck.runFileWithArgs("myFile.ck", "1:2:foo");
* @param filename ChucK file to be run
* @param colonSeparatedArgs arguments to pass to the file separated by colons
* @param colonSeparatedArgs Arguments to pass to the file separated by colons
* @returns Promise to running shred ID
*/
runFileWithArgs(filename: string, colonSeparatedArgs: string): Promise<number>;
Expand All @@ -200,7 +226,7 @@ export default class Chuck extends window.AudioWorkletNode {
/**
* Replace the last currently running shred with a Chuck file to execute.
* Note that the file must already have been loaded via {@link init | filenamesToPreload}, {@link createFile}, or {@link loadFile}
* @param filename file to be replace last
* @param filename File to replace last shred
* @returns Promise to replaced shred ID
*/
replaceFile(filename: string): Promise<{
Expand All @@ -222,8 +248,8 @@ export default class Chuck extends window.AudioWorkletNode {
/**
* Replace the last running shred with a file to execute, passing arguments.
* Note that the file must already have been loaded via {@link init | filenamesToPreload}, {@link createFile}, or {@link loadFile}
* @param filename file to be replace last running shred
* @param colonSeparatedArgs arguments to pass in to file
* @param filename File to be replace last running shred
* @param colonSeparatedArgs Arguments to pass in to file
* @returns Promise to shred ID
*/
replaceFileWithArgs(filename: string, colonSeparatedArgs: string): Promise<{
Expand All @@ -245,7 +271,7 @@ export default class Chuck extends window.AudioWorkletNode {
}>;
/**
* Remove a shred from ChucK VM by ID
* @param shred shred ID to be removed
* @param shred Shred ID to be removed
* @returns Promise to shred ID if removed successfully, otherwise "removing code failed"
*/
removeShred(shred: number | string): Promise<number>;
Expand All @@ -270,7 +296,7 @@ export default class Chuck extends window.AudioWorkletNode {
* or broadcast()). Once signaled, the callback function is invoked. This can
* happen at most once per call.
* @param variable ChucK global event variable to be signaled
* @param callback javascript callback function
* @param callback JavaScript callback function
*/
listenForEventOnce(variable: string, callback: () => void): void;
/**
Expand All @@ -279,15 +305,15 @@ export default class Chuck extends window.AudioWorkletNode {
* invoked. This continues until {@link stopListeningForEvent} is called on the
* specific event.
* @param variable ChucK global event variable to be signaled
* @param callback javascript callback function
* @returns javascript callback ID
* @param callback JavaScript callback function
* @returns JavaScript callback ID
*/
startListeningForEvent(variable: string, callback: () => void): number;
/**
* Stop listening to a specific ChucK event, undoing the process started
* by {@link startListeningForEvent}.
* @param variable ChucK global event variable to be signaled
* @param callbackID callback ID returned by {@link startListeningForEvent}
* @param callbackID Callback ID returned by {@link startListeningForEvent}
*/
stopListeningForEvent(variable: string, callbackID: number): void;
/**
Expand Down
58 changes: 42 additions & 16 deletions dist/Chuck.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,35 @@
import { defer, isPlaintextFile, loadWasm, preloadFiles } from "./utils";
import { InMessage, OutMessage } from "./enums";
/**
* WebChucK extends the Web Audio `AudioWorkletNode` and provides an interface
* to interact with the ChucK Virtual Machine.
* WebChucK extends the Web Audio `AudioWorkletNode` class and provides an
* interface to interact with the ChucK Virtual Machine. Use
* **{@link init | init()}** to create a ChucK instance.
*
* Get started with **{@link init | init()}** to create a ChucK instance.
* `theChuck` is a global variable that is used in the examples below. `init()`
* will create a ChucK instance and an AudioContext if one is not provided.
*
* ```ts
* import { Chuck } from "webchuck";
*
* let theChuck; // global variable
*
* document.getElementById("start").addEventListener("click", async () => {
* if (theChuck === undefined) {
* theChuck = await Chuck.init([]);
* }
* theChuck.runCode("SinOsc osc => dac; 1::second => now;");
* });
* ```
*
* Note that many browsers do not let audio run until there has been user
* interaction (e.g. button press). You can check for a suspended audio context
* and resume like this:
*
* ```ts
* if (theChuck.context.state === "suspended") {
* theChuck.context.resume();
* }
* ```
*/
export default class Chuck extends window.AudioWorkletNode {
/**
Expand Down Expand Up @@ -60,7 +85,7 @@ export default class Chuck extends window.AudioWorkletNode {
* Initialize a ChucK AudioWorkletNode. By default, a new AudioContext is
* created and ChucK is connected to the AudioContext destination.
* **Note:** init() is overloaded to allow for a custom AudioContext,
* custom number of output channels, and custom location of `whereIsChuck`.
* custom number of output channels, and custom URL location of `whereIsChuck`.
* Skip an argument by passing in `undefined`.
*
* @example
Expand Down Expand Up @@ -161,7 +186,7 @@ export default class Chuck extends window.AudioWorkletNode {
* ```ts
* theChuck.loadFile("./myFile.ck");
* ```
* @param url path or url to a file to fetch and load file
* @param url Path or url to a file to fetch and load file
* @returns Promise of fetch request
*/
async loadFile(url) {
Expand Down Expand Up @@ -191,9 +216,10 @@ export default class Chuck extends window.AudioWorkletNode {
// ================== WebChugins ================== //
/**
* Load a single WebChugin (.chug.wasm) via url into WebChucK.
* A list of publicly available WebChugins to load can be found in the {@link https://chuck.stanford.edu/chugins/ | webchugins} folder.
* A list of publicly available WebChugins to load can be found in the {@link https://ccrma.stanford.edu/~tzfeng/static/webchugins/ | webchugins} folder.
* Call this per chugin that you want to load.
* **Note:** WebChugins must be loaded before `theChuck` is initialized.
* @param url url to webchugin to load
* @param url URL to webchugin to load
* @example
* ```ts
* Chuck.loadChugin("https://url/to/myChugin.chug.wasm");
Expand Down Expand Up @@ -325,7 +351,7 @@ export default class Chuck extends window.AudioWorkletNode {
* e.g. Thie is the chuck command line equivalent of `chuck myFile:1:2:foo`
* @example theChuck.runFileWithArgs("myFile.ck", "1:2:foo");
* @param filename ChucK file to be run
* @param colonSeparatedArgs arguments to pass to the file separated by colons
* @param colonSeparatedArgs Arguments to pass to the file separated by colons
* @returns Promise to running shred ID
*/
runFileWithArgs(filename, colonSeparatedArgs) {
Expand Down Expand Up @@ -359,7 +385,7 @@ export default class Chuck extends window.AudioWorkletNode {
/**
* Replace the last currently running shred with a Chuck file to execute.
* Note that the file must already have been loaded via {@link init | filenamesToPreload}, {@link createFile}, or {@link loadFile}
* @param filename file to be replace last
* @param filename File to replace last shred
* @returns Promise to replaced shred ID
*/
replaceFile(filename) {
Expand Down Expand Up @@ -390,8 +416,8 @@ export default class Chuck extends window.AudioWorkletNode {
/**
* Replace the last running shred with a file to execute, passing arguments.
* Note that the file must already have been loaded via {@link init | filenamesToPreload}, {@link createFile}, or {@link loadFile}
* @param filename file to be replace last running shred
* @param colonSeparatedArgs arguments to pass in to file
* @param filename File to be replace last running shred
* @param colonSeparatedArgs Arguments to pass in to file
* @returns Promise to shred ID
*/
replaceFileWithArgs(filename, colonSeparatedArgs) {
Expand Down Expand Up @@ -425,7 +451,7 @@ export default class Chuck extends window.AudioWorkletNode {
// ================== Shred =================== //
/**
* Remove a shred from ChucK VM by ID
* @param shred shred ID to be removed
* @param shred Shred ID to be removed
* @returns Promise to shred ID if removed successfully, otherwise "removing code failed"
*/
removeShred(shred) {
Expand Down Expand Up @@ -469,7 +495,7 @@ export default class Chuck extends window.AudioWorkletNode {
* or broadcast()). Once signaled, the callback function is invoked. This can
* happen at most once per call.
* @param variable ChucK global event variable to be signaled
* @param callback javascript callback function
* @param callback JavaScript callback function
*/
listenForEventOnce(variable, callback) {
const callbackID = this.eventCallbackCounter++;
Expand All @@ -485,8 +511,8 @@ export default class Chuck extends window.AudioWorkletNode {
* invoked. This continues until {@link stopListeningForEvent} is called on the
* specific event.
* @param variable ChucK global event variable to be signaled
* @param callback javascript callback function
* @returns javascript callback ID
* @param callback JavaScript callback function
* @returns JavaScript callback ID
*/
startListeningForEvent(variable, callback) {
const callbackID = this.eventCallbackCounter++;
Expand All @@ -501,7 +527,7 @@ export default class Chuck extends window.AudioWorkletNode {
* Stop listening to a specific ChucK event, undoing the process started
* by {@link startListeningForEvent}.
* @param variable ChucK global event variable to be signaled
* @param callbackID callback ID returned by {@link startListeningForEvent}
* @param callbackID Callback ID returned by {@link startListeningForEvent}
*/
stopListeningForEvent(variable, callbackID) {
this.sendMessage(OutMessage.STOP_LISTENING_FOR_EVENT, {
Expand Down
44 changes: 33 additions & 11 deletions dist/accel/Accel.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,39 @@
import Chuck from "../Chuck";
/**
* Introducing Accel (accelerometer, on mobile) support for WebChucK. Accel wraps
* JavaScript DeviceMotionEvent listeners easing access to mobile device accelerometers
* in WebChucK code.
* Introducing Accel (accelerometer, on mobile) support for WebChucK. Accel
* wraps JavaScript `DeviceMotionEvent` listeners easing access to mobile device
* accelerometers in WebChucK code.
*
* To get started with Accel:
* @example
*
* ```ts
* import { Chuck, Accel } from "webchuck";
*
* const theChuck = await Chuck.init([]);
* const accel = await Accel.init(theChuck); // Initialize Accel
* ```
*
* The `devicemotion` event gives the acceleration of the device on the
* three axes: x, y, and z. Acceleration is expressed in m/s².
* More on the `devicemotion` event can be found online
* {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/devicemotion_event | here }.
*
* iOS devices require that the web developer ask permission from the user to
* access sensors after a button push. This looks like:
*
* ```ts
* let runButton = document.getElementById("run");
*
* runButton.addEventListener("click", async () => {
* // Request iOS accelerometer permission
* if (typeof DeviceMotionEvent.requestPermission === 'function') {
* await DeviceMotionEvent.requestPermission();
* }
*
* await theChuck.loadFile("./yourChuckCode.ck");
* theChuck.runFile("yourChuckCode.ck");
* });
* ```
*/
export default class Accel {
private theChuck;
Expand Down Expand Up @@ -44,13 +66,13 @@ export default class Accel {
*/
enableAccel(): void;
/**
* Disable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is enabled
* accel.disableAccel();
* ```
*/
* Disable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is enabled
* accel.disableAccel();
* ```
*/
disableAccel(): void;
/** @internal */
private handleMotion;
Expand Down
Loading

0 comments on commit 5237e23

Please sign in to comment.