Web Audio API has been around for a while now and there are lots of great articles about it. So I will not go into details regarding the API. What I will tell you is Web Audio can be Angular's best friend if you introduce it well. So let's do this.

 you create a graph of audio nodes that process the sound passing through them. They can change volume, introduce delay or distort the signal. Browsers have special 

 with various parameters to handle this. Initially, one would create them with factory functions of 

const context = new AudioContext();
const gainNode = context.createGain();

But since then they became proper constructors which means you can extend them. This allows us to elegantly and declaratively use Web Audio API in Angular.

Angular directives are classes and they can extend existing native classes. Typical feedback loop to create echo effect with Web Audio looks like this:

const context = new AudioContext();
const gainNode = new GainNode(context);
const delayNode = new DelayNode(context);
const audioSource = new MediaElementAudioSourceNode(context, {
   mediaElement: audioElement.nativeElement,
});

gainNode.gain.value = 0.5;
delayNode.delayTime.value = 0.2;

audioSource.connect(gainNode);
audioSource.connect(context.destination);
gainNode.connect(delayNode);
delayNode.connect(gainNode);
delayNode.connect(context.destination);

We can see that vanilla code is purely imperative. We create objects, set parameters, manually assemble the graph using 

 method. In the example above we use HTML 

 tag. When user presses play he would hear echo on his audio file. We will replicate this case using directives. 

 will be delivered through Dependency Injection.

 have only one parameter each — gain and delay time. That is not just a number, it is an 

. We will see what that means a bit later.

@Directive({
   selector: '[waGainNode]',
   inputs: [
     'channelCount',
     'channelCountMode',
     'channelInterpretation'
   ],
})
export class WebAudioGain extends GainNode {
   @Input('gain')
   set gainSetter(value: number) {
       this.gain.value = value;
   }

   constructor(@Inject(AUDIO_CONTEXT) context: AudioContext) {
       super(context);
   }
}

 decorator we can just list them and they would work properly without a single line of code.

To declaratively link our nodes into graph we will add 

 token. All our directives will provide it.

@Directive({
   selector: '[waGainNode]',
   inputs: [
     'channelCount',
     'channelCountMode',
     'channelInterpretation'
   ],
   exportAs: 'AudioNode',
   providers: [{
     provide: AUDIO_NODE,
     useExisting: forwardRef(() => WebAudioGain),
   }],
})
export class WebAudioGain extends GainNode implements OnDestroy {
   @Input('gain')
   set gainSetter(value: number) {
       this.gain.value = value;
   }

   constructor(
     @Inject(AUDIO_CONTEXT) context: BaseAudioContext,
     @SkipSelf() @Inject(AUDIO_NODE) node: AudioNode | null,
   ) {
       super(context);

       if (node) {
           node.connect(this);
       }
   }

   ngOnDestroy() {
       this.disconnect();
   }
}

Directives take closest node from DI and connect with it. We've also added 

<ng-container waGainNode>
   <ng-container waDelayNode></ng-container>
</ng-container>

We will end a branch and direct sound to the speakers with 

@Directive({
   selector: '[waAudioDestinationNode]',
   exportAs: 'AudioNode',
})
export class WebAudioDestination extends GainNode 
   implements OnDestroy {
   constructor(
       @Inject(AUDIO_CONTEXT) context: AudioContext,
       @Inject(AUDIO_NODE) node: AudioNode | null,
   ) {
       super(context);
       this.connect(context.destination);

       if (node) {
           node.connect(this);
       }
   }

   ngOnDestroy() {
       this.disconnect();
   }
}

To be able to create loops like in the echo example above Dependency Injection is not enough. We will make a special directive. It would allow us to pass node as input to connect to it:

@Directive({
   selector: '[waOutput]',
})
export class WebAudioOutput extends GainNode implements OnDestroy {
   @Input()
   set waOutput(destination: AudioNode | undefined) {
       this.disconnect();

       if (destination) {
           this.connect(destination);
       }
   }

   constructor(
       @Inject(AUDIO_CONTEXT) context: AudioContext,
       @Inject(AUDIO_NODE) node: AudioNode | null,
   ) {
       super(context);
      
       if (node) {
           node.connect(this);
       }
   }

   ngOnDestroy() {
       this.disconnect();
   }
}

 which creates an extra node in the graph. It allows us to disconnect it in 

 easily. We do not need to remember everything that is connected to our directive. We can just disconnect 

The last directive we need to complete our example is a bit different. It's a source node and it's always at the top of our graph. We will put a directive on 

@Directive({
   selector: 'audio[waMediaElementAudioSourceNode]',
   exportAs: 'AudioNode',
   providers: [
       {
           provide: AUDIO_NODE,
           useExisting: forwardRef(() => WebAudioMediaSource),
       },
   ],
})
export class WebAudioMediaSource extends MediaElementAudioSourceNode
   implements OnDestroy {
   constructor(
       @Inject(AUDIO_CONTEXT) context: AudioContext,
       @Inject(ElementRef) {
         nativeElement
       }: ElementRef<HTMLMediaElement>,
   ) {
       super(context, {mediaElement: nativeElement});
   }

   ngOnDestroy() {
       this.disconnect();
   }
}

Now let's create the echo example with our directives:

There are lots of different nodes in Web Audio API but all of them can be implemented using similar approach. Two other important source nodes are 

. Often we do not want to add anything into DOM. And there is no need to provide audio file controls to the user. In that case 

 tag. Only inconvenience is — it works with 

 tag which takes a link to an audio asset. We can create a service to mitigate that:

@Injectable({
   providedIn: 'root',
})
export class AudioBufferService {
   private readonly cache = new Map<string, AudioBuffer>();

   constructor(
      @Inject(AUDIO_CONTEXT) private readonly context: AudioContext
   ) {}

   fetch(url: string): Promise<AudioBuffer> {
       return new Promise<AudioBuffer>((resolve, reject) => {
           if (this.cache.has(url)) {
               resolve(this.cache.get(url));

               return;
           }

           const request = new XMLHttpRequest();

           request.open('GET', url, true);
           request.responseType = 'arraybuffer';
           request.onerror = reject;
           request.onabort = reject;
           request.onload = () => {
               this.context.decodeAudioData(
                   request.response,
                   buffer => {
                       this.cache.set(url, buffer);
                       resolve(buffer);
                   },
                   reject,
               );
           };
           request.send();
       });
   }
}

Now we can create a directive that works both with 

export class WebAudioBufferSource extends AudioBufferSourceNode 
   implements OnDestroy {
   @Input('buffer')
   set bufferSetter(source: AudioBuffer | null | string) {
       this.buffer$.next(source);
   }

   readonly buffer$ = new Subject<AudioBuffer | null | string>();

   constructor(
       @Inject(AudioBufferService) service: AudioBufferService,
       @Inject(AUDIO_CONTEXT) context: AudioContext,
       @Attribute('autoplay') autoplay: string | null,
   ) {
       super(context);

       this.buffer$
           .pipe(
               switchMap(source =>
                   typeof source === 'string'
                       ? service.fetch(source)
                       : of(source),
               ),
           )
           .subscribe(buffer => {
               this.buffer = buffer;
           });

       if (autoplay !== null) {
           this.start();
       }
   }

   ngOnDestroy() {
       this.buffer$.complete();

       try {
           this.stop();
       } catch (_) {}

       this.disconnect();
   }
}

 tag so that sound can start playing immediately.

Audio nodes have a special kind of properties — 

. That's why we used setter for it. Such property value can be automated. You can set it to change linearly, exponentially or even over an array of values in a given time. We need some sort of handler which would allow us to take care of this for all such inputs of our directives. Decorator is a good option for this case:

@Input('gain')
@audioParam('gain')
gainParam?: AudioParamInput;

Decorator would pass processing to a dedicated function:

export type AudioParamDecorator<K extends string> = (
   target: AudioNodeWithParams<K>,
   propertyKey: string,
) => void;

export function audioParam<K extends string>(
   param: K,
): AudioParamDecorator<K> {
   return (target, propertyKey) => {
       Object.defineProperty(target, propertyKey, {
           set(
               this: AudioNode & Record<K, AudioParam>,
               value: AudioParamInput,
           ) {
               processAudioParam(
                   this[param],
                   value,
                   this.context.currentTime,
               );
           },
       });
   };
}

Strong types will not allow us to accidentally use it for a non-existent parameter. So what would 

export type AudioParamAutomation = Readonly<{
   value: number;
   duration: number;
   mode: 'instant' | 'linear' | 'exponential';
}>;

 function translates those objects into native API commands. It's pretty boring so I will just describe the principle. If current value is 0 and we want it to linearly change to 1 in a second we would pass 

{value: 1, duration: 1, mode: ‘linear’}

. For complex automation we would also need to support an array of such objects.

We would typically pass an automation object with short 

. It prevents audible clicking artifacts when parameter changes abruptly. But it's not convenient to do it manually all the time. Let's create a pipe that would take target value, duration and optional mode as arguments:

@Pipe({
   name: 'waAudioParam',
})
export class WebAudioParamPipe implements PipeTransform {
   transform(
       value: number,
       duration: number,
       mode: AudioParamAutomationMode = 'exponential',
   ): AudioParamAutomation {
       return {
           value,
           duration,
           mode,
       };
   }
}

 can be automated by connecting an oscillator to it. Usually a frequency lower than 1 is used and it is called an LFO — Low Frequency Oscillator. It can create movement in sound. In example below it adds texture to otherwise static chords. It modulates frequency of a filter they pass through. To connect oscillator to a parameter we can use our 

 directive. We can access node thanks to 

<ng-container waOscillatorNode frequency="0.2" autoplay>
   <ng-container waGainNode gain="3000">
       <ng-container [waOutput]="filter.frequency"></ng-container>
   </ng-container>
</ng-container>

<ng-container waOscillatorNode autoplay [frequency]="note">
   <ng-container
       #filter="AudioNode"
       waBiquadFilterNode
       type="bandpass"
       frequency="4000"
   >
       <ng-container waAudioDestinationNode></ng-container>
   </ng-container>
</ng-container>

Web Audio API can be used for different things. From real time processing of a voice for a podcast to math computations, Fourier transforms and more. Let's compose a short music piece using our directives:

We will start with simple task — straight drum beat. To count beats we will create a stream and add it to DI:

export const TICK = new InjectionToken<Observable<number>>(
   'Ticks',
   {
     factory: () => interval(250, animationFrameScheduler)
       .pipe(share()),
   }
);

We have 4 beats per measure. Let's map our stream:

kick$ = this.tick$.pipe(map(tick => tick % 4 < 2));

 in the middle of each bar. We would use it to play audio samples:

<ng-container
   *ngIf="kick$ | async; else snare"
   waAudioBufferSourceNode
   autoplay
   buffer="kick.wav"
>
   <ng-container waAudioDestinationNode></ng-container>
</ng-container>
<ng-template #snare>
  <ng-container
     waAudioBufferSourceNode
     autoplay
     buffer="snare.wav"
  >
     <ng-container waAudioDestinationNode></ng-container>
  </ng-container>
</ng-template>

Now let's add melody. We will use numbers to indicate notes where 69 means middle A note. Function that translates this number to frequency can be easily found on Wikipedia. Here's our tune:

const LEAD = [
   70, 70, 70, 70, 70, 70, 70, 68,
   68, 68, 68, 68, 75, 79, 80, 87,
   87, 87, 87, 87, 87, 87, 87, 87,
   87, 87, 87, 87, 84, 80, 79, 75,
   80, 80, 80, 80, 80, 80, 80, 80,
   80, 80, 80, 80, 79, 75, 72, 70,
   70, 70, 70, 70, 70, 70, 70, 68,
   72, 75, 79, 80, 80, 79, 79, 75,
];

Our component will play right frequency for each note each beat:

notes$ = this.tick$.pipe(map(note => toFrequency(LEAD[note % 64])));

And inside its template we will have a real synthesizer! But first we need another pipe. It would automate volume with ADSR-envelope. That means "Attack, Decay, Sustain, Release" and here's how it looks:

In our case we need for the sound to quickly start and then fade away. Pipe is rather simple:

@Pipe({
   name: 'adsr',
})
export class AdsrPipe implements PipeTransform {
   transform(
       value: number,
       attack: number,
       decay: number,
       sustain: number,
       release: number,
   ): AudioParamInput {
       return [
           {
               value: 0,
               duration: 0,
               mode: 'instant',
           },
           {
               value,
               duration: attack,
               mode: 'linear',
           },
           {
               value: sustain,
               duration: decay,
               mode: 'linear',
           },
           {
               value: 0,
               duration: release,
               mode: 'linear',
           },
       ];
   }
}

<ng-container *ngIf="notes$ | async as note">
  <ng-container 
    waOscillatorNode 
    detune="5" 
    autoplay 
    [frequency]="note"
  >
    <ng-container 
      waGainNode
      [gain]="0.1 | adsr : 0 : 0.1 : 0.02 : 0.5"
    >
      <ng-container waAudioDestinationNode></ng-container>
    </ng-container>
  </ng-container>
  <ng-container
    waOscillatorNode
    type="sawtooth"
    autoplay
    [frequency]="note"
  >
    <ng-container
      waGainNode
      [gain]="0.1 | adsr : 0 : 0.1 : 0.02 : 0.5"
    >
      <ng-container
        #feedback="AudioNode"
        waGainNode
        gain="0.7"
      >
        <ng-container waDelayNode delayTime="0.3">
          <ng-container [waOutput]="feedback"></ng-container>
        </ng-container>
        <ng-container waConvolverNode buffer="response.m4a">
          <ng-container waAudioDestinationNode></ng-container>
        </ng-container>
      </ng-container>
      <ng-container waAudioDestinationNode></ng-container>
    </ng-container>
  </ng-container>
</ng-container>

Let's figure out what's going on here. We have two oscillators. First one is just a sine wave passed through ADSR pipe. Second one is same echo loop we've seen, except this time it passes through 

. It creates room acoustics using impulse response. It's a big an interesting subject of its own, but it is outside this article's scope. All other tracks in our song are made similarly. Nodes are connected to each other, parameters are automated with LFOs or change smoothly via our pipes.

I only went over a small portion of this subject, simplifying corner cases. We've made a complete conversion of Web Audio API into declarative Angular open-source library 

If you compare Web Audio to canvas and imperative commands to draw on it, then this library is a lot like SVG.

This library is a part of a bigger project called 

 — an initiative with a goal of creating lightweight, high quality wrappers of native APIs for idiomatic use with Angular. So if you want to try, say, 

 or play with your MIDI keyboard in browser — you are very welcome to browse 

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Writing Retrowave in Angular

Tags

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript