Expertiza_Wiki - User contributions [en]

M1900: Implement missing WebAudio node support

2019-05-03T11:42:24Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we did not actually program in JavaScript for this project. This project involved writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

=== Tracking Issues ===

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

=== Useful Resources ===

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Project Steps ==

=== Initial Steps (OSS Project) ===
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

=== Subsequent Steps (Final Project) ===

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

The rest of our final project just involved implementing methods and therefore did not involve any design choices.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. A user could run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:30:05Z

Masable: /* Introduction */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we did not actually program in JavaScript for this project. This project involved writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

=== Tracking Issues ===

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

=== Useful Resources ===

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Project Steps ==

=== Initial Steps (OSS Project) ===
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

=== Subsequent Steps (Final Project) ===

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

The rest of our final project just involved implementing methods and therefore did not involve any design choices.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:28:44Z

Masable:

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

=== Tracking Issues ===

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

=== Useful Resources ===

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Project Steps ==

=== Initial Steps (OSS Project) ===
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

=== Subsequent Steps (Final Project) ===

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

The rest of our final project just involved implementing methods and therefore did not involve any design choices.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:28:10Z

Masable:

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Project Steps ==

=== Initial Steps (OSS Project) ===
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

=== Subsequent Steps (Final Project) ===

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

The rest of our final project just involved implementing methods and therefore did not involve any design choices.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:26:19Z

Masable: /* Design Choices */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

The rest of our final project just involved implementing methods and therefore did not involve any design choices.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:24:57Z

Masable: /* Final Project */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant the sound moved from left to right over time.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:24:40Z

Masable: /* Final Project */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1. This meant that the sound would move from left to right over time.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:23:44Z

Masable: /* Final Project */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre>
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:23:23Z

Masable: /* Design Choices */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our OSS project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

=== Final Project ===

For our final project, we had a lot of freedom to design our runnable StereoPannerNode example. For the example, we could have set the pan value to anything between -1 (full left pan) and 1 (full right pan) and then changed it any way we wished. At first, we considered setting the pan value to different values at different times, like this:

<pre
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(-1., 2.)),
);
context.message_node(
osc,
AudioNodeMessage::SetParam(ParamType::Pan, UserAutomationEvent::SetValueAtTime(1., 4.)),
);
</pre>

That code would set the pan value to -1 at time = 2 seconds, and then set it to 1 at time = 4 seconds. However, it sounded very weird to have the sound jumping around from place to place.

Eventually, we decided that linearly ramping up the pan value made for the best listening experience. It made the sound continuous but still exemplified what changing the pan value could do.

<pre>
context.message_node(
pan,
AudioNodeMessage::SetParam(
ParamType::Pan,
UserAutomationEvent::RampToValueAtTime(RampKind::Linear, 0., 4.),
),
);
</pre>

Our final version of the StereoPannerNode example involved linearly ramping the pan value from -1 to 0 and then from 0 to 1.

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:16:17Z

Masable: /* OSS Project */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

=== OSS Project ===

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:16:05Z

Masable: /* Design Choices */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

= OSS Project =

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:14:43Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Final Project Step 1 - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Final Project Step 2 - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Final Project Step 3 - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Final Project Step 4 - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:13:39Z

Masable:

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Step 1 of the Final Project - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Step 2 of the Final Project - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Step 3 of the Final Project - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Step 4 of the Final Project - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:11:39Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Step 1 of the Final Project - Oscillator node message]

The purpose of our first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Step 2 of the Final Project - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Step 3 of the Final Project - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Step 4 of the Final Project - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:ConstantSourceNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:10:53Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Step 1 of the Final Project - Oscillator node message]

The purpose of the first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Step 2 of the Final Project - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Step 3 of the Final Project - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Step 4 of the Final Project - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:ConstantSourceNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:10:24Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

Here, each of our pull requests is described in greater detail.

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/media/pull/242 Step 1 of the Final Project - Oscillator node message]

The purpose of the first pull request was to implement an audio node message specific to OscillatorNode. This was within the servo/media project. For this pull request, we had to create a new OscillatorNodeMessage within the oscillator_node.rs file. The purpose of the OscillatorNodeMessage is to set the type of the OscillatorNode. We then had to modify node.rs to utilize the new OscillatorNodeMessage.

[https://github.com/servo/servo/pull/23282 Step 2 of the Final Project - Type attribute for OscillatorNode interface]

The purpose of our second pull request was to implement the type attribute for the OscillatorNode interface within the main servo project. This required enabling the setter throws and OscillatorType attribute within the OscillatorNode.webidl file. More importantly, it involved modifying the oscillatornode.rs file to include methods to set and get the type of the OscillatorNode. This was challenging because we did not realize at first that we needed to wrap the oscillator_type in a cell in order to achieve interior mutability. Initially, we were handing references to the setters and getters of the DOM struct members, which did not expose the set and get methods we were calling. We had to wrap the oscillator_type in a cell to give mutable references instead.

[https://github.com/servo/media/pull/243 Step 3 of the Final Project - StereoPannerNode backend]

For our third pull request, we had to implement the backend for the StereoPannerNode in servo/media. Then we had to create a runnable example that utilizes the StereoPannerNode. We designed our example so that we would initialize a StereoPannerNode with the default pan value of 0. Then, we would set the pan value to -1. Next, we would linearly ramp up the pan value to 0 and then to 1. Ideally, someone would be able to run this example and listen to the StereoPannerNode through speakers as its pan value changed over time, causing the sound to move from left to right.

[https://github.com/servo/servo/pull/23281 Step 4 of the Final Project - StereoPannerNode DOM]

For our fourth and last pull request, we created the DOM interface for StereoPannerNode and implemented the createStereoPannerNode API for BaseAudioContext within the main servo project. We had to create a few new files for this, since there was no existing stereopannernode.rs or StereoPannerNode.webidl. We also had to modify audionode.rs to add constraints when creating a StereoPannerNode, such as to ensure that there are not more than two channels and that the channel count mode is not set to max. In that case, we had to return a NotSupported error.

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:ConstantSourceNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-05-03T11:06:19Z

Masable: /* Completed Work */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

Our Pull Requests:

[https://github.com/servo/servo/pull/23152 OSS Project]

[https://github.com/servo/media/pull/242 Step 1 of the Final Project - Oscillator node message]

[https://github.com/servo/servo/pull/23282 Step 2 of the Final Project - Type attribute for OscillatorNode interface]

[https://github.com/servo/media/pull/243 Step 3 of the Final Project - StereoPannerNode backend]

[https://github.com/servo/servo/pull/23281 Step 4 of the Final Project - StereoPannerNode DOM]

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:ConstantSourceNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:16:05Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:ConstantSourceNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:ConstantSourceNodeDOMResized.png

2019-04-13T02:15:45Z

Masable:

File:StereoPannerNodeDOMResized.png

2019-04-13T02:14:23Z

Masable: uploaded a new version of "File:StereoPannerNodeDOMResized.png"

M1900: Implement missing WebAudio node support

2019-04-13T02:13:00Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOMResized.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:StereoPannerNodeDOMResized.png

2019-04-13T02:12:53Z

Masable:

M1900: Implement missing WebAudio node support

2019-04-13T02:11:30Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOM.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:StereoPannerNodeDOM.png

2019-04-13T02:11:15Z

Masable: uploaded a new version of "File:StereoPannerNodeDOM.png"

M1900: Implement missing WebAudio node support

2019-04-13T02:10:22Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOM.png|400 px]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:10:07Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOM.png|200 px]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:09:15Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNodeDOM.png]]</div>

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:StereoPannerNodeDOM.png

2019-04-13T02:08:31Z

Masable:

File:ConstantSourceNodeDOM.png

2019-04-13T02:08:13Z

Masable:

M1900: Implement missing WebAudio node support

2019-04-13T02:03:11Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:02:33Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// utilize the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:02:09Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// [SetterThrows]
// line below utilizes the new OscillatorType audio node message
attribute OscillatorType type;
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:00:48Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// [SetterThrows]
// attribute OscillatorType type;
// attributes such as frequency, gain, etc. go here
};
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T02:00:18Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// [SetterThrows]
// attribute OscillatorType type;
// attributes such as frequency, gain, etc. go here
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:58:28Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

<pre>
[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// [SetterThrows]
attribute OscillatorType type;
</pre>

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:57:50Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.

[Exposed=Window,
Constructor (BaseAudioContext context, optional OscillatorOptions options)]
interface OscillatorNode : AudioScheduledSourceNode {
// [SetterThrows]
// attribute OscillatorType type;

* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:54:52Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:OscillatorNode.png]]</div>

* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:OscillatorNode.png

2019-04-13T01:54:28Z

Masable:

M1900: Implement missing WebAudio node support

2019-04-13T01:50:16Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:BaseAudioContext.png]]</div>

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:BaseAudioContext.png

2019-04-13T01:49:48Z

Masable:

M1900: Implement missing WebAudio node support

2019-04-13T01:41:06Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.
** We will follow the example in servo/media/examples/panner.rs to create our runnable example.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:38:28Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:38:09Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:38:00Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:StereoPannerNode.png]]</div>

[[File:StereoPannerNode.png]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:34:57Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

[[File:StereoPannerNode.png]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

File:StereoPannerNode.png

2019-04-13T01:33:58Z

Masable:

M1900: Implement missing WebAudio node support

2019-04-13T01:31:29Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

[[File:ECE517 M1900 StereoPannerNode.png|ECE517 M1900 StereoPannerNode]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:30:14Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

[[File:ECE517_M1900_StereoPannerNode.png]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:29:49Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

[[File:Example.jpg]]
[[File:ECE517 M1900 StereoPannerNode.png]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.

M1900: Implement missing WebAudio node support

2019-04-13T01:28:52Z

Masable: /* Planned Work (Design Document) */

== Introduction ==
Major browsers support the WebAudio standard which can be used to create complex media playback applications from low-level building blocks. [https://github.com/servo/servo Servo] is a new, experimental browser that supports some of these building blocks (called audio nodes); the goal of [https://github.com/servo/servo/wiki/WebAudio-JS-interfaces-student-project this project] is to improve compatibility with web content that relies on the WebAudio API by implementing missing pieces of incomplete node types (OscillatorNode) along with entire missing nodes (ConstantSourceNode and StereoPannerNode).

Although the GitHub description for our project is titled "Implement JS support for several missing WebAudio node types", we are not actually programming in JavaScript for this project. This project involves writing Rust code to implement the backend functionality of the WebAudio API, which the end user can then write JavaScript code to utilize. Therefore, the code snippets on this page are entirely in the Rust language. The only portion of our project written in JavaScript/HTML are the tests; however, the tests are not the main focus of this project (feature implementation is).

== Tracking Issues ==

[https://github.com/servo/servo/issues/21803 ConstantSourceNode]

[https://github.com/servo/servo/issues/21797 StereoPannerNode]

== Useful Resources ==

* [https://github.com/servo/media#servo-media Setup] for modifying the standalone media backend implementation
* [https://github.com/servo/media/tree/master/audio/src Implementation] of audio node processing algorithms
* [https://github.com/servo/media/tree/master/examples Runnable examples] of audio node processing algorithms
* [https://github.com/servo/servo/pull/21750 Example] pull request implementing a missing node type in Servo (another example)
* [https://github.com/servo/media/pull/131 Example] pull request implementing the processing backend for a missing node type
* [https://github.com/servo/servo/#the-servo-parallel-browser-engine-project Setup] for making changes to Servo's code
* [https://doc.servo.org/script/dom/index.html#adding-a-new-dom-interface Documentation] for introducing new WebIDL-based DOM interfaces to Servo
* [https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies Documentation] for integrating a version of servo-media that contains your local changes into your local Servo build

== Initial Steps (OSS Project) ==
* Email the mozilla.dev.servo mailing list (be sure to subscribe to it first!) introducing your group and asking any necessary questions.
* Create the DOM interface for ConstantSourceNode and implement the createConstantSource API for BaseAudioContext.
* Connect the DOM interface to the underlying backend node by processing the unimplemented message type.
* Update the expected test results for the relevant tests.

== Subsequent Steps (Final Project) ==

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.

== Design Choices ==

Our project did not involve any design patterns since we were just implementing methods.

However, we faced multiple options of how to create and implement the ConstantSourceNode. Initially, we tried to model it on the OscillatorNode implementation, but faced a build error.

<pre>
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We eventually learned that the ConstantSourceNode should not have a parent field because it does not inherit from anything.

<pre>
let node_options =
options
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
</pre>

We faced other design choices that we had to adjust from the OscillatorNode implementation. For example, we encountered errors with this code.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions;
</pre>

We then realized that ConstantSourceNodeOptions needed to be cast as a different type in order to function correctly.

<pre>
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
</pre>

== Completed Work ==

We created the DOM interface for ConstantSourceNode and implemented the CreateConstantSource API for BaseAudio Context. The connection between the DOM interface and the underlying backend node was already [https://github.com/servo/media/pull/164 implemented by other contributors] before we started the project.

[https://github.com/servo/servo/pull/23152 Our Pull Request]

DOM implementation:
<pre>
use crate::dom::audioparam::AudioParam;
use crate::dom::audioscheduledsourcenode::AudioScheduledSourceNode;
use crate::dom::baseaudiocontext::BaseAudioContext;
use crate::dom::bindings::codegen::Bindings::AudioNodeBinding::{
ChannelCountMode, ChannelInterpretation,
};
use crate::dom::bindings::codegen::Bindings::AudioParamBinding::AutomationRate;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::ConstantSourceNodeMethods;
use crate::dom::bindings::codegen::Bindings::ConstantSourceNodeBinding::{
self, ConstantSourceOptions,
};
use crate::dom::bindings::error::Fallible;
use crate::dom::bindings::reflector::reflect_dom_object;
use crate::dom::bindings::root::{Dom, DomRoot};
use crate::dom::window::Window;
use dom_struct::dom_struct;
use servo_media::audio::node::AudioNodeInit;
use servo_media::audio::constant_source_node::ConstantSourceNodeOptions as ServoMediaConstantSourceOptions;
use servo_media::audio::param::ParamType;
use std::f32;

#[dom_struct]
pub struct ConstantSourceNode {
source_node: AudioScheduledSourceNode,
offset: Dom<AudioParam>,
}

impl ConstantSourceNode {
#[allow(unrooted_must_root)]
pub fn new_inherited(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<ConstantSourceNode> {
let node_options =
options
.parent
.unwrap_or(2, ChannelCountMode::Max, ChannelInterpretation::Speakers);
let source_node = AudioScheduledSourceNode::new_inherited(
AudioNodeInit::ConstantSourceNode(options.into()),
context,
node_options,
0, /* inputs */
1, /* outputs */
)?;
let node_id = source_node.node().node_id();
let offset = AudioParam::new(
window,
context,
node_id,
ParamType::Offset,
AutomationRate::A_rate,
1.,
f32::MIN,
f32::MAX,
);

Ok(ConstantSourceNode {
source_node,
offset: Dom::from_ref(&offset),
})
}

#[allow(unrooted_must_root)]
pub fn new(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
let node = ConstantSourceNode::new_inherited(window, context, options)?;
Ok(reflect_dom_object(
Box::new(node),
window,
ConstantSourceNodeBinding::Wrap,
))
}

pub fn Constructor(
window: &Window,
context: &BaseAudioContext,
options: &ConstantSourceOptions,
) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new(window, context, options)
}
}

impl ConstantSourceNodeMethods for ConstantSourceNode {
fn Offset(&self) -> DomRoot<AudioParam> {
DomRoot::from_ref(&self.offset)
}
}

impl<'a> From<&'a ConstantSourceOptions> for ServoMediaConstantSourceOptions {
fn from(options: &'a ConstantSourceOptions) -> Self {
Self {
offset: *options.offset,
}
}
}
</pre>

Constant Source Node Webidl DOM:
<pre>
dictionary ConstantSourceOptions: AudioNodeOptions {
float offset = 1;
};

[Exposed=Window, Constructor (BaseAudioContext context, optional ConstantSourceOptions options)]
interface ConstantSourceNode : AudioScheduledSourceNode {
readonly attribute AudioParam offset;
};
</pre>

CreateConstantSource API for BaseAudio Context:
<pre>
use crate::dom::constantsourcenode::ConstantSourceNode;
fn CreateConstantSource(&self) -> Fallible<DomRoot<ConstantSourceNode>> {
ConstantSourceNode::new( &self.global().as_window(), &self, &ConstantSourceOptions::empty())
}
</pre>

Connection between the DOM interface and the underlying backend node (implemented by other contributors):

<pre>
AudioNodeInit::ConstantSourceNode(options) => {
Box::new(ConstantSourceNode::new(options, ch))
}
</pre>

== Planned Work (Design Document) ==

As we continue our project, it will likely not involve any design patterns since we will just be implementing methods. Here is what we must do and our plan for how do it:

* Implement an audio node message that is specific to OscillatorNode (use BiquadFilterNode as a model) which updates the node's oscillator type.
** The audio node message specification is in servo/media/audio/src/node.rs. We will use this specification for guidance.
* Implement the type attribute setter for the OscillatorNode interface which uses the new oscillator node message.
** We will accomplish this by modifying servo/components/script/dom/webidls/OscillatorNode.webidl.
* Implement the backend for StereoPannerNode in the media crate by creating a new node implementation using PannerNode as a guide. The processing algorithm is described in the specification. Create a runnable example based on the example for PannerNode.
** The goal for the StereoPannerNode implementation is that the user should be able to specify a pan value between -1 (full left pan) and 1 (full right pan) and the StereoPannerNode will adjust the gain on each of the two speakers accordingly.

[[File:ECE517 M1900 StereoPannerNode.png|thumb|StereoPannerNode diagram for ECE 517 (M1900).]]

** We will follow the example in servo/media/examples/panner.rs to create our runnable example.
* Create the DOM interface for StereoPannerNode and implement the createStereoPannerNode API for BaseAudioContext.
** We already created the DOM interface for ConstantSourceNode and implemented the createConstantSourceNode API for BaseAudioContext, so we will follow the same procedure when creating the DOM interface for StereoPannerNode and implementing the createStereoPannerNode API.

== Testing ==

'''Testing from Command Line'''

After following the setup instructions in the [https://github.com/servo/servo#the-servo-parallel-browser-engine-project Servo readme], cloning the repository, and changing directories into it, you can build the project with the following command from the terminal (the readme includes the different build commands to use depending on your OS). Note that it may take a long time to build the project.

<pre>
./mach build --release
</pre>

After building, you can run the relevant tests with the following command.

<pre>
./mach test-wpt tests/wpt/web-platform-tests/webaudio/the-audio-api/the-constantsourcenode-interface/
</pre>

You will notice that all tests pass as expected.

'''Testing from UI'''

Our project cannot be tested from a UI since it involves the Servo project.