ng-web-audio v0.0.5

Web Audio API for Angular

This is a library for declarative use of Web Audio API with Angular 6+. It is a complete conversion to declarative Angular directives, if you find any inconsistencies or errors, please file an issue. Watch out for 💡 emoji in this README for addition features and special use cases.

How to use

You can build audio graph with directives. For example, here's a typical echo feedback loop:

<audio src="/demo.wav" MediaElementAudioSourceNode>
    <ng-container #node="AudioNode" [DelayNode]="delayTime">
        <ng-container [GainNode]="gain">
            <ng-container [Output]="node"></ng-container>
            <ng-container AudioDestinationNode></ng-container>
        </ng-container>
    </ng-container>
    <ng-container AudioDestinationNode></ng-container>
</audio>

Note that single input nodes, such as GainNode or DelayNode use directive name as input alias for underlying gain or delayTime parameters. Whereas more complex nodes use respective parameters names.

💡 AudioBufferService

This library has AudioBufferService with fetch method, returning Promise which allows you to easily turn your hosted audio file into AudioBuffer through GET requests. Result is stored in service's cache so same file is not requested again while application is running.

This service is also used within directives that have AudioBuffer inputs (such as AudioBufferSourceNode or ConvolverNode) so you can just pass string URL, as well as an actual AudioBuffer. For example:

<button
    #source="AudioNode"
    buffer="/demo.wav"
    AudioBufferSourceNode
    (click)="source.start()"
>
    Play
    <ng-container AudioDestinationNode></ng-container>
</button>

Supported nodes

You can use following audio nodes through directives of the same name:

Terminal nodes

• AudioContext

  💡 Not required if you only need one, global context will be created when needed

  💡 Also gives you access to AudioListener parameters such as positionX

• OfflineAudioContext

  💡 Additionally supports empty autoplay attribute similar to audio tag so it would start rendering immediately

  💡 Also gives you access to AudioListener parameters such as positionX

• AudioDestinationNode

  💡 Use it to terminate branch of your graph

  💡 can be used multiple times inside single BaseAudioContext referencing the same BaseAudioContext.destination

  💡 Has (quiet) output to watch for particular graph branch going silent

Sources

• AudioBufferSourceNode

  💡 Additionally supports setting URL to media file as buffer so it will be fetched and turned into AudioBuffer

  💡 Additionally supports empty autoplay attribute similar to audio tag so it would start playing immediately

• MediaElementAudioSourceNode

• OscillatorNode

  💡 Additionally supports empty autoplay attribute similar to audio tag so it would start playing immediately

Processors

• BiquadFilterNode

• ConvolverNode

  💡 Additionally supports setting URL to media file as buffer so it will be fetched and turned into AudioBuffer

• DelayNode

• GainNode
• PannerNode
• StereoPannerNode
• WaveShaperNode

💡 Special cases

• Use Output directive when you need non-linear graph (see feedback loop example above) or to manually connect AudioNode to AudioNode or AudioParam
• Use PeriodicWave pipe to create PeriodicWave for OscillatorNode
• All node directives are exported as AudioNode so you can use them with template reference variables (see feedback loop example above)

💡 Tokens

• You can inject BaseAudioContext through AUDIO_CONTEXT token
• AudioContext is created by default with default options when token is requested
• You can also provide custom BaseAudioContext through that token
• All node directives provide underlying AudioNode as AUDIO_NODE token

Browser support

Note that some features (AudioWorklet etc.) were added later and are supported only by more recent versions

IMPORTANT: You must add ng-web-audio/polyfill to polyfills.ts used in angular.json if you want to support Safari

💡 StereoPannerNode is emulated with PannerNode in browsers that do not support it yet

💡 positionX (orientationX) and other similar properties of AudioListener and PannerNode fall back to setPosition (setOrientation) method if browser does not support it

Demo

You can try online demo here

TODO

• IIRFilterNode, however it is not supported by Safari and generally BiquadFilterNode is sufficient
• Add remaining audio nodes:
  • ChannelMergerNode
  • ChannelSplitterNode
  • ConstantSourceNode
  • ScriptProcessorNode
• Add sophisticated AudioParam manipulations such as ramping and scheduled changes
• AudioWorklet concept
• Streaming concept
  • MediaStreamAudioDestinationNode
  • MediaStreamAudioSourceNode
• Add some sort of SSR fallback so it doesn't crash in Angular Universal environment