https://github.com/ej-shafran/react-sound-visualizer
https://github.com/ej-shafran/react-sound-visualizer
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ej-shafran/react-sound-visualizer
- Owner: ej-shafran
- Created: 2023-02-17T15:45:38.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T07:24:51.000Z (about 2 months ago)
- Last Synced: 2025-02-26T16:09:20.543Z (about 2 months ago)
- Language: TypeScript
- Size: 323 KB
- Stars: 14
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- my-awesome-list - react-sound-visualizer - shafran | 16 | (TypeScript)
README
# react-sound-visualizer
## Description
This library acts as a lightweight React wrapper for [sound-visualizer](https://github.com/ej-shafran/sound-visualizer).
You can check it out by visiting [the codesandbox](https://codesandbox.io/s/react-sound-visualizer-demo-gi8uhd).
## Getting Started
### Installation
```bash
npm install react-sound-visualizer
```
### Usage
You'll mainly want to use the `Visualizer` component (you can see more documentation for it below):
```tsx
import { useEffect, useState } from 'react';
import { Visualizer } from 'react-sound-visualizer';
function App() {
const [audio, setAudio] = useState(null);
useEffect(() => {
navigator.mediaDevices
.getUserMedia({
audio: true,
video: false,
})
.then(setAudio);
}, []);
return (
{({ canvasRef, stop, start, reset }) => (
<>
Start
Stop
Reset
>
)}
);
}
export default App;
```
If you need even more control over the visualization, the `useVisualizer` hook (used by `Visualizer` behind the scenes) is also exported.
## Documentation
### Components
#### Visualizer
##### Props
| **Prop** | **Type** | **Default** | **Explanation** | |
|-----------------|--------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
| **audio** | `MediaStream \| null` | | The audio to visualize. Can be `null` since usually that's how your state will be initialized, but note that the functions will not be defined while it is `null`. | |
| **children** | `React.FC` | | See **Types** section below. | |
| **mode** | `"current" \| "continuous"` | `"continuous"` | The visualizer version to use. You can check out the [sound-visualizer](https://github.com/ej-shafran/sound-visualizer) docs to learn more about what each version means. | |
| **lineWidth** | `number \| "thin" \| "thick" \| "default"` | `"default"` | The width of each line drawn onto the canvas for the visualization. If a thickness string is provided, it will be translated into a percentage of the canvas's width; if a number is provided it will be used a `px` value. | |
| **strokeColor** | `string` | `"#000"` | The color of each line drawn onto the canvas for the visualization. | |
| **autoStart** | `boolean` | `false` | When set to `true`, the `start` function will be called as soon as the `audio` is available. | |
| **slices** | `number` | `100` | The number of slices drawn onto the canvas to make up the wave. *Only available as a prop when `mode` is `"continuous"`* | |
| **heightNorm** | `number` | `1` | A number used to normalize the height of the wave; the wave function is multiplied by this number, so a number larger than 1 will exaggerate the height of the wave, while a number between 0 and 1 will minimize it. *Only available as a prop when `mode` is `"current"`* | |
### Hooks
#### useVisualizer
```typescript
export function useVisualizer(
audio: MediaStream | null,
canvas: HTMLCanvasElement | null,
options?: UseVisualizerOptions
): Partial;
```
The `useVisualizer` hook acts as a simple wrapper for both the `currentVisualizer` and `continuousVisualizer` functions from
`sound-visualizer`, which allows the user to pass `null` for the `audio` and `canvas` parameters
and returns an empty object if `null` is passed for either.
It also wraps the `VisualizerFunctions` that are returned in a `useMemo` hook.
(*Note:* if you would rather not use a memo, you can directly use the `visualizerWrapper` function)
### Types
#### VisualizerChildrenProps
```typescript
export interface VisualizerChildrenProps {
canvasRef: (canvas: HTMLCanvasElement) => void;
start?: () => void;
stop?: () => void;
reset?: () => void;
}
```
The `Visualizer`'s `children` prop must be a function that returns a `ReactNode`.
The `canvasRef` must be passed as the `ref` prop to an HTML `canvas` element,
*or else the visualizer will not draw anything!*
#### UseVisualizerOptions
```typescript
export type UseVisualizerOptions =
| { mode: "current" } & DrawCurrentOptions
| { mode?: "continuous" & DrawContinuousOptions
```
Where `DrawCurrentOptions` and `DrawContinuousOptions` are the types from `sound-visualizer`.
## Notes
The `visualizerWrapper` function, used internally by `useVisualizer`, is exposed for convenience.