Skip to content

Feat/docs/interface update #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 29, 2024
Merged

Feat/docs/interface update #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8231f8b
docs: update interface docs and readme
Jul 26, 2024
9c63b0b
Update basic-interfaces.md
maciejmakowski2003 Jul 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 2 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,15 @@
The main goal of the project is to reproduce the Web Audio API as accurate as possible in the React Native environment.
# React Native Audio Context

## Internal Documentation

- [Basic interfaces description](./internal-docs/basic-interfaces.md)
[Basic interfaces description](./internal-docs/basic-interfaces.md)

## Installation

```sh
npm install react-native-audio-context
```

## Usage

```js
import { multiply } from 'react-native-audio-context';

// ...

const result = multiply(3, 7);
```

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
Expand Down
259 changes: 214 additions & 45 deletions internal-docs/basic-interfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

## Project goal

The main goal of the project is to reproduce the Web Audio API as accurate as possible in the React Native environment.
The main goal of the project is to recreate the Web Audio API as accurate as possible in the React Native environment.

## Interfaces

The document introduces the basic interfaces that we want to recreate.
The document introduces the basic interfaces of React Native Audio Context library.

1. [AudioContext](#audiocontext)
2. [AudioNode](#audionode)
Expand All @@ -16,105 +16,274 @@ The document introduces the basic interfaces that we want to recreate.
6. [OscillatorNode](#oscillatornode)
7. [GainNode](#gainnode)
8. [StereoPannerNode](#stereopannernode)
9. [BiquadFilterNode](#biquadfilternode)

### AudioContext

The `AudioContext` interface is the underlying audio context that manages the state of the entire audio application.
The `AudioContext` interface is the underlying audio context that manages the state of the entire audio application. It controls both the creation of nodes and the execution of audio processing. You have to create it at first, because everything happens inside it. It is recommended to create one `AudioContext` instance ane reuse it.

#### Attributes
#### Constructor

- **`currentTime`**: Representing an ever-increasing hardware time in seconds. It starts at 0.
- **`destination`**: Output node that is typically connected to speakers.
- **`sampleRate`**: Audio sampling rate in hertz.
&ensp;**`AudioContext()`**<br>
&ensp;&ensp;&ensp;*Creates and returns new AudioContext instance*


#### Properties

&ensp;**`destination`**<br>
&ensp;&ensp;&ensp;*Returns an `AudioDestinationNode` representing final destination of all audio in the context.*

&ensp;**`sampleRate`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns a floating point number representing sample rate, in samples per second used by all nodes in this audio context*

&ensp;**`currentTime`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns a floating point number representing an ever-increasing hardware time in seconds. It starts at 0.*

&ensp;**`state`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns a current state of this audio context. There are two states: running and closed.*

#### Methods

- **`createBuffer()`**: Creates the audio buffer.
- **`createGain()`**: Creates a gain node.
- **`createOscillator()`**: Creates an oscillator node.
- **`createStereoPanner()`**: Creates a stereo panning node.
&ensp;**`createGain()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `GainNode`.*

&ensp;**`createOscillator()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `OscillatorNode`.*

&ensp;**`createStereoPannerNode()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `StereoPannerNodeNode`.*

&ensp;**`createBiquadFilter()`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns and creates `BiquadFilterNode`.*

&ensp;**`close()`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Closes audio context, releasing any system resources that it uses.*

#### Code snippets

```js
const audioContext = new AudioContext();

const oscillator = audioContext.createOscillator();
const gain = audioContext.createGain();
const panner = audioContext.createStereoPannerNode();

const destination = audioContext.destination;
```

---

### AudioNode

The `AudioNode` interface is the base interface for all audio nodes in the audio processing graph.
The `AudioNode` interface is the generic interface for all audio nodes in the audio processing graph.

#### Properties

#### Attributes
&ensp;**`context`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the `AudioContext` associated with this node.*

- **`context`**: Context associated with AudioNode.
- **`numberOfInputs`**: Number of inputs feeding the node. Source nodes are defined as nodes having value 0 for this attribute
- **`numberOfOutputs`**: Number of outputs coming out of the node. Destination nodes are defined as nodes having value 0 for this attribute
&ensp;**`numberOfInputs`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the number of inputs feeding the node. Source nodes are defined as nodes having value 0 for this property*

&ensp;**`numberOfOutputs`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the number of outputs coming out of the node. Destination nodes are defined as nodes having value 0 for this property*

#### Methods

- **`connect(destination, output, input)`**: Connects the current audio node to another audio node or parameter.
- **`disconnect(destination, output, input)`**: Disconnects the current audio node from another audio node or parameter.
&ensp;**`connect(node: AudioNode)`**<br>
&ensp;&ensp;&ensp;*Connects the current node to another audio node.*

&ensp;**`disconnect(node: AudioNode)`**<br>
&ensp;&ensp;&ensp;*Disconnects the current node from another audio node.*

#### Code snippets

```js
const oscillator = audioContext.createOscillator();
const gain = audioContext.createGain();

oscillator.connect(gain);
gain.connect(audioContext.destination);
```

#### Processing Graph

Processing graph - a graph, or more precisely, a chain of interconnected nodes through which the audio signal flows. Each node can be independently configured and connected to other nodes.


```mermaid
graph TD;
A[Oscillator] --> B[GainNode];
B --> C[PannerNode];
C --> D[Destination];
E[Oscillator] --> F[GainNode];
F --> G[BiquadFilter]
G --> D
```

The example graph consists of two oscillators. The first of them is equipped with GainNode and PannerNode, which allows you to control the volume and panning of the sound. Second one is connected to GainNode and BiquadFilter, providing simple low-order filtering. Both oscillators are connected to destination, which means they will be heard at the same time

---

### AudioScheduledSourceNode

The `AudioScheduledSourceNode` is an interface representing several types of audio source node. Inherits from `AudioNode`.

#### Methods

- **`start(time)`**: Schedules the node to begin playback at specified time. If no time is given, starts immediately.
- **`stop(time)`**: Schedules the node to stop playing at specified time. If no time is given, stops immediately.
&ensp;**`start(time: number)`**<br>
&ensp;&ensp;&ensp;*Schedules the node to begin playback at specified time. If no time is given, starts immediately.*

&ensp;**`stop(time: number)`**<br>
&ensp;&ensp;&ensp;*Schedules the node to stop playing at specified time. If no time is given, stops immediately.*

#### Code snippets

```js
oscillator.start(audioContext.currentTime)
oscillator.stops(audioContext.currentTime + 0.5)
```

---

### AudioDestinationNode

The `AudioDestinationNode` is an interface representing end destination of audio graph. Inherits from `AudioNode`.
The `AudioDestinationNode` is an interface representing the final destination of audio graph. Inherits from `AudioNode`.

---

### AudioParam

The `AudioParam` interface represents audio parameters that can be time-modulated.

#### Attributes
#### Properties

&ensp;**`value`**<br>
&ensp;&ensp;&ensp;*Returns the current value of this parameter. Initially set to defaultValue.*

&ensp;**`defaultValue`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the initial value of this parameter.*

- **`value`**: The current value of the parameter.
&ensp;**`minValue`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the minimum value of this parameter*

&ensp;**`maxValue`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Returns the maximum value of this parameter*

#### Methods

- **`setValueAtTime(value, startTime)`**: Sets the parameter value at the specified time.
- **`linearRampToValueAtTime(value, endTime)`**: Linearly ramps the value of a parameter to a specified value in a specified time.
- **`exponentialRampToValueAtTime(value, endTime)`**: Exponentially changes the value of a parameter to the specified value over the specified time.
&ensp;**`setValueAtTime(value: number, startTime: number)`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Sets the parameter `value` at the specified time given by `startTime`.*

&ensp;**`linearRampToValueAtTime(value: number, endTime: number)`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Schedules a gradual linear change in the value. New `value` will be reached in the `endTime`.*

&ensp;**`exponentialRampToValueAtTime(value: number, endTime: number)`**:exclamation: not yet implemented :exclamation:<br>
&ensp;&ensp;&ensp;*Schedules a gradual exponential change in the value. New `value` will be reached in the `endTime`.*

#### Code snippets

```js
gain.gain.setValueAtTime(1.0, time);
gain.gain.exponentialRampToValueAtTime(0.01, time + 0.5);
```

---

### OscillatorNode

The `OscillatorNode` interface represents an oscillator node that generates sounds at a specific frequency and waveform. Inherits from `AudioScheduledSourceNode`.

#### Attributes
#### Constructor

&ensp;**`AudioContext.createOscillator()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `OscillatorNode` instance in given `AudioContext`.*

#### Properties

&ensp;**`frequency`**<br>
&ensp;&ensp;&ensp;*Returns `AudioParam` representing the frequency of oscillation in hertz.*

&ensp;**`detune`**<br>
&ensp;&ensp;&ensp;*Returns `AudioParam` representing detuning of oscillation in cents.*

&ensp;**`type`**<br>
&ensp;&ensp;&ensp;*Returns string representing shape of waveform to play. Available values: `"sine"`, `"square"`, `"sawtooth"`, `"triangle"`.*

#### Code snippets

```js
const oscillator = audioContext.createOscillator();
oscillator.frequency.value = 800;
oscillator.detune.value = 30;
oscillator.type = "sawtooth";

oscillator.start();
```

- **`frequency`**: `AudioParam` - frequency parameter.
- **`detune`**: `AudioParam` - detune parameter.
- **`type`**: wave type (`sine`, `square`, `sawtooth`, `triangle`).
---

### GainNode

The `GainNode` interface represents a gain node that allows you to control the volume of the audio signal. Inherits from `AudioNode`.

#### Attributes
#### Constructor

&ensp;**`AudioContext.createGain()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `GainNode` instance in given `AudioContext`.*

#### Properties

- **`gain`**: `AudioParam` - gain parameter.
&ensp;**`gain`**<br>
&ensp;&ensp;&ensp;*Returns `AudioParam` representing the amount of gain to apply. Gain value has to be in range <0,1>.*

#### Code snippets

```js
const gain = audioContext.createGain();
gain.gain.value = 0.5;
```

---

### StereoPannerNode

The `StereoPannerNode` interface represents a stereo panning node that allows you to control the position of sound in stereo space. Inherits from `AudioNode`.

#### Attributes
#### Constructor

- **`pan`**: `AudioParam` - panning parameter.
&ensp;**`AudioContext.createStereoPanner()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `StereoPannerNode` instance in given `AudioContext`.*

## Processing Graph
#### Properties

Processing graph - a graph, or more precisely, a chain of interconnected nodes through which the audio signal flows. Each node can be independently configured and connected to other nodes.
&ensp;**`pan`**<br>
&ensp;&ensp;&ensp;*Returns `AudioParam` representing the amount of panning to apply. Pan value has to be in range <-1,1>. `-1`- full left, `1`- full right.*

### Example processing graph
#### Code snippets

```mermaid
graph TD
A[Oscillator] --> B[GainNode]
B --> C[PannerNode]
C --> D[Destination]
E[Oscillator] --> F[GainNode]
F --> D
```js
const panner = audioContext.createStereoPanner();
panner.pan.value = -0.5;
```

The example graph consists of two oscillators. The first of them is equipped with GainNode and PannerNode, which allows you to control the volume and panning of the sound. Only the GainNode is connected to the second oscillator, which allows you to change its volume. Both oscillators are connected to destination, which means they will be heard at the same time
---

### BiquadFilterNode

The `BiquadFilterNode` interface represents a simple low-order filter. It can represent different kinds of filters, tone control devices, and graphic equalizers

#### Creation

&ensp;**`AudioContext.createBiquadFilter()`**<br>
&ensp;&ensp;&ensp;*Returns and creates `BiquadFilterNode` instance in given `AudioContext`.*

#### Properties

:exclamation: not yet implemented :exclamation:

#### Code snippets

```js
const filter = audioContext.createBiquadFilter();
```