From 16fde907ad6adf78ccd1499422e178a58746a38f Mon Sep 17 00:00:00 2001 From: Yushin Washio Date: Sun, 26 Dec 2021 00:04:05 +0100 Subject: [PATCH] update README --- README.md | 116 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 75 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 74da750..d9020bd 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,17 @@ # Web Audio Oscilloscope -A highly customizable oscilloscope for web Audio that supports any source supported by the browser, and renders on a HTML5 canvas. +A highly customizable oscilloscope for web Audio that supports any source supported by the browser, +with a provided renderer drawing on a HTML5 canvas. ![Imgur](https://i.imgur.com/df8zx4v.gif) ## ✨[Try The Live Demo](https://theanam.github.io/webaudio-oscilloscope/) -> If you are using v1 and planning to move to v2 or v3, the constructor changes a little bit. +> If you are using v3 or older and planning to move to v4, the +> constructor changes significantly. +> There also was a little bit of change to the constructor from v1 to +> v2. ### Installation ```bash @@ -30,15 +34,18 @@ First create a canvas element in your page: In your JavaScript File: ```js -import {Oscilloscope, createAudioContext, getUserMedia} from "webaudio-oscilloscope"; +import { + Oscilloscope, createAudioContext, getUserMedia, Renderer +} from "webaudio-oscilloscope"; function startOsc(){ let ctx = createAudioContext(); let cvs = document.querySelector(".osc"); + let renderer = Renderer(cvs); getUserMedia({audio: true}) .then(stream=>{ // Works with any supported source let src = ctx.createMediaStreamSource(stream); - let osc = new Oscilloscope(ctx, src, cvs); + let osc = new Oscilloscope(ctx, src, renderer); osc.start(); }); } @@ -52,12 +59,13 @@ document.querySelector(".start").addEventListener("click",startOsc); #### Since Creating *Oscilloscope from `mediaStream`* is a very common user case, There's a shorthand function for this.The above code can also be written like: ```js -import {MediaStreamOscilloscope} from "webaudio-oscilloscope"; +import {MediaStreamOscilloscope, Renderer} from "webaudio-oscilloscope"; function startOsc(){ let cvs = document.querySelector(".osc"); + let renderer = Renderer(cvs); navigator.mediaDevices.getUserMedia({audio: true}) .then(stream=>{ - let osc = new MediaStreamOscilloscope(stream, cvs); + let osc = new MediaStreamOscilloscope(stream, renderer); osc.start(); }); } @@ -70,24 +78,24 @@ document.querySelector(".start").addEventListener("click",startOsc); ```js import {Oscilloscope} from "webaudio-oscilloscope"; - new Oscilloscope(AudioContext, AudioSource, CanvasElement, AudioDestination, [fft, init,primer]); + new Oscilloscope(AudioContext, AudioSource, Renderer, [AudioDestination, fft]); ``` Argument | Required | Default | Description | ---------|----------| --------|-------------| audioContext | true | null | The Audio Context to use. [See MDN](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext)| AudioSource | true | null | The Audio Source to listen to. [See MDN](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext)| -CanvasElement | true | null | The HTML5 canvas element to render the Oscilloscope in| +Renderer | true | null | Renderer for the Oscilloscope, e. g. to render it in a HTML5 canvas| Audio Destination | false | null | The Node to pass the output to. e.g destination or any additional node| fft | false | 2048 | The fft size for the AnalyserNode. The larger the number the smoother the graph the more resource it will consume| init | false | null | Function to run on the canvas before starting to draw. Gets called only once before starting the drawing Cycle. See below for details| primer | false | null | The function that gets caled before every render cycle. Useful for stying the Output| ### Oscilloscope from Media Stream: -It's a common use case to create Oscilloscope from Media Stream, Hence, there's a short form. +It's a common use case to create Oscilloscope from Media Stream, Hence, there's a short form. ```js import {MediaStreamOscilloscope} from "webaudio-oscilloscope"; -new MediaStreamOscilloscope(mediaStream, CanvasElement, AudioDestination, [fft, init,primer]); +new MediaStreamOscilloscope(mediaStream, Renderer, [AudioDestination, fft]); ``` This function takes a `mediaStream` object instead of an `audioContext` and `audioSource`, the rest of the parameters are the same. This also produces an `Oscilloscope` instance. @@ -106,58 +114,84 @@ Resets the oscilloscope canvas. Does not take any arguments. Reset oscilloscope This directly relate to the *highly customizable* claim in the title. If you know your way around [HTML5 Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API), You'll feel at home. -The Oscilloscope can be customized by using, the `init` and `primer` arguments in the constructor. If you need one of the two, just pass `null` for the other one. It will be ignored. +The Oscilloscope can be customized by either +* extending the provided `Renderer` and customizing the `init`, `primer` + and `osc` methods or +* writing your own renderer from scratch (you aren’t even required to + use a HTML5 Canvas in that case). + +#### Renderer constructor: + +The provided renderer class is constructed with just one argument: + +Argument | Required | Default | Description | +---------|----------| --------|-------------| +CanvasElement | true | null | The HTML5 canvas element to render the Oscilloscope in| #### init() [Function]: -> If you want to change the colors or line width of the oscilloscope, use a custom `init` function. Oscilloscope background is filled with the `fillStyle` property of the canvas 2d context, and `strokeStyle` property affetcs the graph color. +> If you need to do some initialization at the end of the Oscilloscope +> instantiation (just once), you can provide a custom `init` method. +> Oscilloscope background is filled with the `fillStyle` property of the +> canvas 2d context, and `strokeStyle` property affects the graph color. -You can create a function like the one below and pass it in the constructor. In fact this is the default init function. You can do stuff like setting the default fill and stroke colors,setting line width etc. For example, to set the fill and stroke style of the canvas: +You can create a custom renderer like the one below and pass it in the +constructor. +You can do stuff like setting the default fill and stroke colors,setting line width etc. For example, to set the fill and stroke style of the canvas: ```js -function customInit(context, width, height){ - ctx.fillStyle = "#000"; - ctx.strokeStyle = "#0f0"; +class CustomRenderer extends Renderer{ + init(){ + this.fillStyle = "#000"; + this.strokeStyle = "#0f0"; + } } // Then Initiate the Oscilloscope like this: -new Oscilloscope(AudioContext, AudioSource, CanvasElement, AudioDestination, 2042, customInit); +const customRenderer = new CustomRenderer(cvs); +new Oscilloscope(AudioContext, AudioSource, customRenderer, AudioDestination, 2042); +``` + +For this simple task you can of course likewise just set those +attributes: + +```js +class CustomRenderer extends Renderer{ + fillStyle = "#000" + strokeStyle = "#0f0" +} ``` #### primer() [Function]: This function gets called before every render. If you need to draw anything (a graph or maybe some values), you can do it here. For example: the default primer function fills the background with the default fill color(black): ```js -function customPrimer(ctx, width, height){ - ctx.fillRect(0,0,width,height); +class CustomRenderer extends Renderer{ + primer(){ + self.cctx.fillRect(0,0,width,height); + } } -// Then Initiate the Oscilloscope like this: -new Oscilloscope(AudioContext, AudioSource, CanvasElement, AudioDestination, 2042, null, customPrimer); ``` For example: If you want to render your oscilloscope on a graph, try this primer function: ```js -function fancyGraph(ctx,width,height){ - let backstrokeStyle = ctx.strokeStyle; - ctx.strokeStyle = "#444"; - ctx.fillRect(0,0,width,height); - ctx.beginPath(); - for(let i=0; i