### SiriWave Container Initialization Examples

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Examples demonstrating how to initialize SiriWave by providing the container element using different methods.

```typescript
// By ID
const siriWave = new SiriWave({
  container: document.getElementById("wave-container")
});
```

```typescript
// By query selector
const siriWave = new SiriWave({
  container: document.querySelector(".wave-visualization")
});
```

```typescript
// By direct reference
const container = document.createElement("div");
container.style.width = "640px";
container.style.height = "200px";
document.body.appendChild(container);

const siriWave = new SiriWave({ container });
```

--------------------------------

### Install SiriWave Package

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/START_HERE.md

Use npm to install the SiriWave library. This is the first step before using it in your project.

```bash
npm install siriwave
```

--------------------------------

### start()

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Starts the SiriWave animation. This method should be called after initialization to begin the visual effect.

```APIDOC
## start()

Starts the animation.
```

--------------------------------

### Minimal SiriWave Setup

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Use this for the simplest initialization, providing only the container element.

```typescript
new SiriWave({ container: element })
```

--------------------------------

### start()

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Starts or resumes the wave animation. It resets the phase to 0 and begins the draw cycle. Calling this multiple times while the animation is already running has no effect. Throws an error if the instance has been disposed.

```APIDOC
## start()

### Description
Starts or resumes the animation. Resets the phase to 0 and begins the draw cycle. Calling start() multiple times while running has no effect.

### Method
`start(): void`

### Throws
`Error` with message "This instance of SiriWave has been disposed, please create a new instance" if the instance has been disposed.

### Example
```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  autostart: false
});

// Later, start the animation
siriWave.start();
```
```

--------------------------------

### Basic SiriWave Setup and Control

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/START_HERE.md

Initialize SiriWave with container, style, and dimensions. Control animation speed, amplitude, and manage the instance lifecycle.

```typescript
import SiriWave from "siriwave";

const siriWave = new SiriWave({
  container: document.getElementById("wave"),
  style: "ios9",
  width: 640,
  height: 200
});

// Control
siriWave.setSpeed(0.5);
siriWave.setAmplitude(1.2);
siriWave.stop();
siriWave.dispose();
```

--------------------------------

### Run Development Server with Watch Mode

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Use this command to create a watchable build with RollupJS and start a local server for live preview of changes during development.

```sh
npm dev
```

--------------------------------

### Basic SiriWave Setup with Default Types

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Instantiates SiriWave with default types inferred from the options object. Ensure the container element exists in the DOM.

```typescript
import SiriWave from "siriwave";

const container = document.getElementById("wave");
const siriWave = new SiriWave({
  container,
  style: "ios9"
});
```

--------------------------------

### Project Navigation Structure

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/00-DELIVERY-MANIFEST.md

Illustrates the hierarchical structure for navigating the SiriWave project documentation, starting from the entry point and branching out to detailed and deep-dive resources.

```markdown
START_HERE.md (entry point)
    ↓
Quick Answers: REFERENCE_GUIDE.md (lookup tables)
    ↓
Detailed: README.md (concepts) → api-reference/ (specifics)
    ↓
Deep Dive: architecture.md → internal-methods.md
    ↓
Complete Index: INDEX.md
```

--------------------------------

### Control Autostart Animation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Determine whether the animation starts immediately upon initialization. Setting autostart to false requires explicit calls to the start() method.

```typescript
// Start immediately (default)
const siriWave1 = new SiriWave({
  container: element,
  autostart: true
});

// Manual control
const siriWave2 = new SiriWave({
  container: element,
  autostart: false
});

// Start later
setTimeout(() => siriWave2.start(), 2000);
```

--------------------------------

### Rendering Cost Example Calculation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/architecture.md

Demonstrates a practical calculation of the total operations per frame for a specific canvas size and configuration, highlighting the performance at 60fps.

```plaintext
Canvas: 640 * 200 = 128,000 pixels (clear operation)
Curves: 4 * (2 * 25 / 0.02) = 4 * 2500 = 10,000 points
Total: ~138,000 operations per frame at 60fps = ~8.3M ops/sec
```

--------------------------------

### Start SiriWave Animation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Starts or resumes the SiriWave animation. Call this after initializing the instance or after stopping it. The animation resets its phase to 0 when started.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  autostart: false
});

// Later, start the animation
siriWave.start();
```

--------------------------------

### Animated Microphone Visualization with SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Configure SiriWave for animated microphone visualization. This setup starts the wave on audio input and dynamically updates its speed and amplitude based on audio analysis.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave"),
  style: "ios9",
  autostart: false,
  speed: 0.2,
  amplitude: 0.5
});

// Start on mic input
avigator.mediaDevices.getUserMedia({ audio: true })
  .then(stream => {
    siriWave.start();
    
    // Update visualization based on audio analysis
    const audioContext = new AudioContext();
    const analyser = audioContext.createAnalyser();
    // ... audio processing code ...
    
    function updateWave() {
      const dataArray = new Uint8Array(analyser.frequencyBinCount);
      analyser.getByteFrequencyData(dataArray);
      
      // Map average frequency to speed (0.1 to 0.8)
      const avg = dataArray.reduce((a, b) => a + b) / dataArray.length;
      const speed = 0.1 + (avg / 256) * 0.7;
      siriWave.setSpeed(speed);
      
      // Map frequency variance to amplitude (0.5 to 1.5)
      const variance = dataArray.reduce((sum, val) => 
        sum + Math.pow(val - avg, 2)
      ) / dataArray.length;
      const amplitude = 0.5 + (Math.sqrt(variance) / 128) * 1;
      siriWave.setAmplitude(amplitude);
      
      requestAnimationFrame(updateWave);
    }
    updateWave();
  });
```

--------------------------------

### Instantiate SiriWave with Custom Options

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Example demonstrating how to create a new SiriWave instance with a custom set of options. This includes specifying the container, style, dimensions, animation speed, amplitude, autostart behavior, lerp speed, and global composite operation.

```typescript
const options: Options = {
  container: document.getElementById("wave-container"),
  style: "ios9",
  width: 640,
  height: 200,
  speed: 0.3,
  amplitude: 1.2,
  autostart: true,
  lerpSpeed: 0.15,
  globalCompositeOperation: "screen"
};

const siriWave = new SiriWave(options);
```

--------------------------------

### Custom Curve Implementation Example

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ice-curve-interface.md

Implement the ICurve interface to create a custom circle-based curve visualization. This example shows how to integrate a custom curve into a SiriWave instance.

```typescript
import type { ICurve } from "siriwave";
import SiriWave from "siriwave";

class CircleCurve implements ICurve {
  private ctrl: SiriWave;
  private radius: number;
  
  constructor(ctrl: SiriWave, radius: number) {
    this.ctrl = ctrl;
    this.radius = radius;
  }
  
  draw(): void {
    const { ctx } = this.ctrl;
    
    ctx.beginPath();
    ctx.arc(
      this.ctrl.width / 2,
      this.ctrl.height / 2,
      this.radius * Math.sin(this.ctrl.phase),
      0,
      2 * Math.PI
    );
    ctx.strokeStyle = "rgba(255, 255, 255, 0.8)";
    ctx.lineWidth = 2;
    ctx.stroke();
  }
}

// Use custom curve
const siriWave = new SiriWave({
  container: document.getElementById("wave"),
  autostart: false
});

// Replace curves with custom implementation
siriWave.curves = [new CircleCurve(siriWave, 50)];
siriWave.start();
```

--------------------------------

### Example Usage of globalAttFn

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/internal-methods.md

Demonstrates example values for the globalAttFn method, showing the attenuation factor at different normalized distances from the center.

```typescript
globalAttFn(0)    // 1.0
globalAttFn(0.5)  // 0.704
globalAttFn(1.0)  // 0.003
globalAttFn(2.0)  // 0.0001
```

--------------------------------

### SiriWave Setup with Explicit Type Annotation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Provides explicit type annotations for the options object, enhancing type safety and code readability. Requires importing the 'Options' type.

```typescript
import SiriWave, { Options } from "siriwave";

const options: Options = {
  container: document.getElementById("wave"),
  style: "ios",
  width: 800,
  height: 300,
  speed: 0.25,
  amplitude: 0.8
};

const siriWave = new SiriWave(options);
```

--------------------------------

### Configure Classic SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Example of configuring a classic SiriWave with multiple curve layers, adjusting attenuation, line width, opacity, and optional colors.

```typescript
const definition: IClassicCurveDefinition[] = [
  { attenuation: -2, lineWidth: 1, opacity: 0.1 },
  { attenuation: -6, lineWidth: 1, opacity: 0.2 },
  { attenuation: 4,  lineWidth: 1, opacity: 0.4 },
  { attenuation: 2,  lineWidth: 1.5, opacity: 0.6 },
  { attenuation: 1,  lineWidth: 1.5, opacity: 1, color: "200,200,255" }
];

const siriWave = new SiriWave({
  container: element,
  style: "ios",
  curveDefinition: definition
});
```

--------------------------------

### Initialize New Cycle of Waves (TypeScript)

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/internal-methods.md

Starts a new animation cycle by initializing a set of waves with random parameters. This method is called when the animation starts or when a previous cycle has fully completed.

```typescript
private spawn(): void
```

--------------------------------

### Example Usage of getRandomRange (TypeScript)

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/internal-methods.md

Demonstrates calling getRandomRange with different input ranges to generate random values.

```typescript
getRandomRange([0, 10])      // Random value 0.0 to 10.0
getRandomRange([500, 2000])  // Random value 500 to 2000
getRandomRange([-3, 3])      // Random value -3 to 3
```

--------------------------------

### Configure iOS 9 SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Example of configuring an iOS 9 SiriWave with multiple curve layers, specifying colors and support lines.

```typescript
const definition: IiOS9CurveDefinition[] = [
  { color: "255,255,255", supportLine: true },
  { color: "100,150,255" },  // blue
  { color: "255,100,150" }   // pink
];

const siriWave = new SiriWave({
  container: element,
  style: "ios9",
  curveDefinition: definition
});
```

--------------------------------

### dispose()

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Stops the animation and removes the canvas element from the DOM, effectively cleaning up the SiriWave instance. Calling `start()` after `dispose()` will result in an error.

```APIDOC
## dispose()

Stops the animation and destroys the canvas, by removing it from the DOM. Subsequent `start()` calls on this SiriWave instance will fail with an exception.
```

--------------------------------

### Customizing iOS9 Wave Generation with Ranges

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Example demonstrating how to configure custom random parameter ranges for iOS9 SiriWave instances to alter wave behavior like number of curves, amplitude, and speed.

```typescript
const ranges: IiOS9Ranges = {
  noOfCurves: [3, 8],
  amplitude: [0.4, 1.5],
  offset: [-4, 4],
  width: [0.8, 2.5],
  speed: [0.3, 0.9],
  despawnTimeout: [800, 2500]
};

const siriWave = new SiriWave({
  container: element,
  style: "ios9",
  ranges: ranges
});
```

--------------------------------

### SiriWave Initialization and Control

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/README.md

Demonstrates how to initialize SiriWave with basic configuration, control animation properties like speed and amplitude, and clean up the instance.

```APIDOC
## SiriWave Initialization and Control

### Description
This section covers the basic usage of the SiriWave library, including initialization, controlling animation parameters, and cleanup.

### Initialization
To initialize SiriWave, you need to provide a container element and a configuration object.

```typescript
import SiriWave from "siriwave";

// Get the container element from the DOM
const container = document.getElementById("wave-container");

// Initialize SiriWave with configuration
const siriWave = new SiriWave({
  container: container, // The DOM element to render the wave in
  style: "ios9",      // Animation style: "ios" or "ios9"
  width: 640,         // Width of the canvas
  height: 200         // Height of the canvas
});
```

### Controlling Animation
Once initialized, you can control the animation's speed and amplitude.

```typescript
// Set the animation speed (e.g., 0.5)
siriWave.setSpeed(0.5);

// Set the animation amplitude (e.g., 1.2)
siriWave.setAmplitude(1.2);
```

### Cleanup
To stop the animation and release resources, use the `stop` and `dispose` methods.

```typescript
// Stop the animation
siriWave.stop();

// Dispose of the SiriWave instance and clean up resources
siriWave.dispose();
```
```

--------------------------------

### Initialize SiriWave with a Script Tag

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/START_HERE.md

Demonstrates how to include the SiriWave library using a direct script tag and initialize a new SiriWave instance.

```html
<script src="https://unpkg.com/siriwave/dist/siriwave.umd.min.js"></script>
<script>
  const sw = new SiriWave({ container: element });
</script>
```

--------------------------------

### Initialize SiriWave in Browser

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Create a container element and instantiate SiriWave, passing the container and desired dimensions.

```html
<div id="siri-container"></div>
<script>
  var siriWave = new SiriWave({
    container: document.getElementById("siri-container"),
    width: 640,
    height: 200,
  });
</script>
```

--------------------------------

### Dynamic SiriWave Control

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Control the SiriWave instance after initialization using methods like start, stop, setSpeed, setAmplitude, and dispose.

```typescript
const sw = new SiriWave({ container: element });
sw.start();
sw.setSpeed(0.5);
sw.setAmplitude(1.2);
sw.stop();
sw.dispose();
```

--------------------------------

### Initialize SiriWave with Options

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Create a new SiriWave instance by passing a configuration object to the constructor. Customize aspects like the container, style, speed, and color.

```typescript
new SiriWave({
  container: document.body,
  style: "ios9",
  amplitude: 0.5,
  speed: 0.1,
  color: "#00ff00"
})
```

--------------------------------

### SiriWave Constructor

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Initializes a new SiriWave instance. The `container` option is required.

```APIDOC
## constructor SiriWave

### Description
Initializes a new SiriWave instance. The `container` option is required.

### Signature
`constructor(options: Options)`

### Returns
SiriWave

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (Options) - Required - Configuration options for SiriWave, including the `container` element.
```

--------------------------------

### Configure Siriwave with dat.GUI

Source: https://github.com/kopiro/siriwave/blob/master/index.html

Uses dat.GUI to provide interactive controls for adjusting the speed, amplitude, and color of the classic Siriwave instance. This requires the dat.GUI library to be included.

```javascript
window.onload = function () {
  var gui = new dat.GUI();
  gui.add(SW, "speed", 0, 1);
  gui.add(SW, "amplitude", 0, 3);
  gui.addColor(SW, "color");
  var gui9 = new dat.GUI();
  gui9.add(SW9, "speed", 0, 1);
  gui9.add(SW9, "amplitude", 0, 3);
};
```

--------------------------------

### Initialize Wave Rendering (draw - Step 1)

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/internal-methods.md

Initializes the wave by calling the `spawn()` method if `spawnAt` is 0. This is the first step in the `draw()` method's algorithm.

```typescript
if (this.spawnAt === 0) {
  this.spawn();
}
```

--------------------------------

### Options Type

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Defines the configuration options for initializing a SiriWave instance.

```APIDOC
## Options Type

### Description

Configuration object for SiriWave.

### Fields

- **container (HTMLElement)** - Required - The HTML element to contain the canvas.
- **style ('ios' | 'ios9')?** - Optional - The visual style of the wave.
- **ratio (number)?** - Optional - The device pixel ratio.
- **speed (number)?** - Optional - The initial animation speed.
- **amplitude (number)?** - Optional - The initial wave amplitude.
- **frequency (number)?** - Optional - The wave frequency.
- **color (string)?** - Optional - The color of the wave.
- **cover (boolean)?** - Optional - Whether the wave should cover the container.
- **width (number)?** - Optional - The width of the canvas.
- **height (number)?** - Optional - The height of the canvas.
- **autostart (boolean)?** - Optional - Whether to start the animation automatically.
- **pixelDepth (number)?** - Optional - The pixel depth for rendering.
- **lerpSpeed (number)?** - Optional - The speed for interpolation.
- **curveDefinition (ICurveDefinition[])?** - Optional - Custom curve definitions.
- **ranges (IiOS9Ranges)?** - Optional - Range settings for iOS 9 style.
- **globalCompositeOperation (GlobalCompositeOperation)?** - Optional - Canvas global composite operation.
```

--------------------------------

### Complete SiriWave Configuration

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Initialize SiriWave with all available configuration options for detailed control over appearance and behavior.

```typescript
new SiriWave({
  container: element,
  style: "ios9",
  width: 640,
  height: 200,
  speed: 0.3,
  amplitude: 1.0,
  pixelDepth: 0.02,
  lerpSpeed: 0.1,
  autostart: true
})
```

--------------------------------

### SiriWave Class

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

The main SiriWave class for creating and controlling wave animations. It provides methods to start, stop, and dispose of the animation, as well as to adjust its speed and amplitude.

```APIDOC
## SiriWave Class

### Description

Represents the core SiriWave animation controller.

### Methods

- **constructor(options: Options)**: Initializes a new SiriWave instance with the provided options.
- **start()**: Starts the wave animation.
- **stop()**: Stops the wave animation.
- **dispose()**: Cleans up resources and stops the animation.
- **setSpeed(value: number)**: Sets the animation speed.
- **setAmplitude(value: number)**: Sets the animation amplitude.

### Properties

- **opt (Options)**: The configuration options for the SiriWave instance.
- **phase (number)**: The current phase of the wave animation.
- **run (boolean)**: Indicates whether the animation is currently running.
- **curves (ICurve[])**: An array of curve objects used in the animation.
- **speed (number)**: The current speed of the animation.
- **amplitude (number)**: The current amplitude of the wave.
- **width (number)**: The width of the canvas.
- **height (number)**: The height of the canvas.
- **heightMax (number)**: The maximum height of the wave.
- **color (string)**: The color of the wave.
- **canvas (HTMLCanvasElement | null)**: The canvas element used for rendering.
- **ctx (CanvasRenderingContext2D)**: The 2D rendering context for the canvas.
- **interpolation ({ speed: number | null; amplitude: number | null })**: Interpolation settings for speed and amplitude.
```

--------------------------------

### Responsive SiriWave Container Handling

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/README.md

Implement responsive behavior for SiriWave by re-initializing the instance on window resize. This ensures the visualization adapts to container changes.

```typescript
const container = document.getElementById("wave");
let siriWave = new SiriWave({
  container,
  cover: true,
  autostart: false
});

function handleResize() {
  siriWave.dispose();
  siriWave = new SiriWave({
    container,
    cover: true
  });
}

window.addEventListener("resize", handleResize);
```

--------------------------------

### SiriWave Class Definition

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Defines the SiriWave class, its constructor, public API methods for controlling wave behavior (start, stop, dispose, setSpeed, setAmplitude), and its public properties.

```typescript
export default class SiriWave {
  constructor(options: Options)
  
  // Public API
  start(): void
  stop(): void
  dispose(): void
  setSpeed(value: number): void
  setAmplitude(value: number): void
  
  // Public Properties
  opt: Options
  phase: number
  run: boolean
  curves: ICurve[]
  speed: number
  amplitude: number
  width: number
  height: number
  heightMax: number
  color: string
  canvas: HTMLCanvasElement | null
  ctx: CanvasRenderingContext2D
  interpolation: { speed: number | null; amplitude: number | null }
}
```

--------------------------------

### Package Exports Configuration

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Defines the entry points for the SiriWave package across different module systems and environments.

```json
{
  "main": "./dist/siriwave.esm.js",
  "module": "./dist/siriwave.esm.js",
  "browser": "./dist/siriwave.umd.js",
  "types": "./dist/types"
}
```

--------------------------------

### SiriWave Constructor Options

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Overview of all available options for the SiriWave constructor, including required and optional parameters.

```typescript
new SiriWave({
  container: HTMLElement,      // REQUIRED
  style?: "ios" | "ios9",      // Optional
  ratio?: number,
  speed?: number,
  amplitude?: number,
  frequency?: number,
  color?: string,
  cover?: boolean,
  width?: number,
  height?: number,
  autostart?: boolean,
  pixelDepth?: number,
  lerpSpeed?: number,
  curveDefinition?: ICurveDefinition[],
  ranges?: IiOS9Ranges,
  globalCompositeOperation?: GlobalCompositeOperation
})
```

--------------------------------

### Dispose SiriWave Instance

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Stops the animation, removes the canvas element from the DOM, and nullifies internal references. After disposal, the SiriWave instance cannot be reused and attempting to start it will result in an error.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container")
});

// Later, clean up
siriWave.dispose();
// siriWave.start() would now throw an error
```

--------------------------------

### Basic SiriWave Initialization and Control

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/README.md

Initialize SiriWave with a container element and minimal configuration. Control animation speed and amplitude, then stop and dispose of the instance.

```typescript
import SiriWave from "siriwave";

// Create container
const container = document.getElementById("wave-container");

// Initialize with minimal config
const siriWave = new SiriWave({
  container,
  style: "ios9",      // "ios" or "ios9"
  width: 640,
  height: 200
});

// Control the animation
siriWave.setSpeed(0.5);
siriWave.setAmplitude(1.2);

// Stop and clean up
siriWave.stop();
siriWave.dispose();
```

--------------------------------

### Build All Targets

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Execute this command to perform a final build of all project targets.

```sh
npm build
```

--------------------------------

### stop()

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Stops the animation without destroying the canvas. It cancels the animation frame request and clears pending timeouts, resetting the phase to 0. The instance can be restarted using the `start()` method.

```APIDOC
## stop()

### Description
Stops the animation but does not destroy the canvas. Cancels the active animation frame request and clears any pending timeouts. Resets phase to 0. The instance can be restarted with `start()`.

### Method
`stop(): void`

### Example
```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container")
});

// Stop the animation
siriWave.stop();

// Resume later
siriWave.start();
```
```

--------------------------------

### SiriWave Initialization with GlobalCompositeOperation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

Demonstrates initializing SiriWave with different globalCompositeOperation values for iOS9 style waves. Use 'lighter' for additive blending or 'multiply' for darker blending.

```typescript
// Brighter overlapping waves (default)
const siriWave1 = new SiriWave({
  container: element,
  style: "ios9",
  globalCompositeOperation: "lighter"
});

// Darker overlapping waves
const siriWave2 = new SiriWave({
  container: element,
  style: "ios9",
  globalCompositeOperation: "multiply"
});
```

--------------------------------

### Stop SiriWave Animation

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Stops the currently running SiriWave animation. The animation can be resumed later by calling start(). This method cancels animation frame requests and clears pending timeouts.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container")
});

// Stop the animation
siriWave.stop();

// Resume later
siriWave.start();
```

--------------------------------

### Microphone-Driven Visualization with SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/README.md

Initialize SiriWave and connect it to microphone input for real-time audio visualization. Requires user permission for microphone access.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave"),
  autostart: false
});

// Initialize audio context
const audioContext = new (window.AudioContext || window.webkitAudioContext)();
const analyser = audioContext.createAnalyser();

navigator.mediaDevices.getUserMedia({ audio: true })
  .then(stream => {
    const source = audioContext.createMediaStreamSource(stream);
    source.connect(analyser);
    siriWave.start();
    
    // Update visualization
    function animate() {
      const dataArray = new Uint8Array(analyser.frequencyBinCount);
      analyser.getByteFrequencyData(dataArray);
      
      const avg = dataArray.reduce((a, b) => a + b) / dataArray.length;
      siriWave.setAmplitude(avg / 128);
      
      requestAnimationFrame(animate);
    }
    animate();
  });
```

--------------------------------

### Get Default iOS9 Curve Definitions

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Use this static method to retrieve the default array of curve definitions for the iOS9 style. This array includes definitions for a support line and three colored waves.

```typescript
static getDefinition(): IiOS9CurveDefinition[]
```

--------------------------------

### SiriWave Constructor Options

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/types.md

The SiriWave constructor accepts an options object to configure the wave's appearance, animation, and behavior. Below are the available properties and their descriptions.

```APIDOC
## SiriWave Constructor Options

### Description
Configuration object passed to the SiriWave constructor.

### Parameters
#### Request Body
- **container** (HTMLElement) - Required - DOM container element where canvas will be appended
- **style** (CurveStyle) - Optional - Wave style: "ios" or "ios9" (Default: "ios")
- **ratio** (number) - Optional - Pixel density ratio for high-DPI displays (Default: window.devicePixelRatio || 1)
- **speed** (number) - Optional - Animation speed multiplier (0 to 1+ typical) (Default: 0.2)
- **amplitude** (number) - Optional - Wave height multiplier (Default: 1)
- **frequency** (number) - Optional - Number of complete waves (ios style only) (Default: 6)
- **color** (string) - Optional - Hex color code (ios style only) (Default: "#fff")
- **cover** (boolean) - Optional - If true, canvas fills container 100%; if false, uses pixel dimensions (Default: false)
- **width** (number) - Optional - Canvas width in pixels (Default: container.offsetWidth)
- **height** (number) - Optional - Canvas height in pixels (Default: container.offsetHeight)
- **autostart** (boolean) - Optional - Start animation immediately after construction (Default: true)
- **pixelDepth** (number) - Optional - Distance step when drawing curves. Smaller = smoother but slower (Default: 0.02)
- **lerpSpeed** (number) - Optional - Interpolation speed for property transitions (0 to 1) (Default: 0.1)
- **curveDefinition** (ICurveDefinition[]) - Optional - Custom curve definitions; null uses style defaults (Default: null)
- **ranges** (IiOS9Ranges) - Optional - Custom parameter ranges (ios9 style only) (Default: null)
- **globalCompositeOperation** (GlobalCompositeOperation) - Optional - Canvas blend mode (ios9 style only) (Default: "lighter")

### Request Example
```typescript
const options = {
  container: document.getElementById("wave-container"),
  style: "ios9",
  width: 640,
  height: 200,
  speed: 0.3,
  amplitude: 1.2,
  autostart: true,
  lerpSpeed: 0.15,
  globalCompositeOperation: "screen"
};

const siriWave = new SiriWave(options);
```
```

--------------------------------

### Customizing iOS9 Curve Ranges

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Instantiate SiriWave with custom ranges for parameters like amplitude, width, and speed to alter the wave's appearance and behavior. This example demonstrates how to override default ranges for a more personalized wave effect.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios9",
  ranges: {
    noOfCurves: [3, 6],           // More curves
    amplitude: [0.5, 1.2],         // Larger amplitudes
    offset: [-5, 5],               // Wider offset range
    width: [0.5, 2],               // Narrower waves
    speed: [0.3, 0.8],             // Slower curves
    despawnTimeout: [1000, 3000]   // Longer lifetime
  }
});
```

--------------------------------

### Get Default Classic Curve Definitions

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/classic-curve.md

The static getDefinition() method returns an array of default curve definitions used for the classic iOS SiriWave style. These definitions specify attenuation, line width, and opacity for each layer of the wave.

```javascript
static getDefinition(): IClassicCurveDefinition[]
```

```javascript
[
  { attenuation: -2, lineWidth: 1, opacity: 0.1 },
  { attenuation: -6, lineWidth: 1, opacity: 0.2 },
  { attenuation: 4,  lineWidth: 1, opacity: 0.4 },
  { attenuation: 2,  lineWidth: 1.5, opacity: 0.6 },
  { attenuation: 1,  lineWidth: 1.5, opacity: 1 }
]
```

```typescript
// Get default curve definitions
const defaultDefs = ClassicCurve.getDefinition();

// Use defaults with SiriWave
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios"
  // curveDefinition defaults to ClassicCurve.getDefinition()
});

// Or customize the definitions
const customDefs = [
  { attenuation: -2, lineWidth: 2, opacity: 0.15 },
  { attenuation: -6, lineWidth: 2, opacity: 0.3 },
  { attenuation: 4,  lineWidth: 2, opacity: 0.5 },
  { attenuation: 2,  lineWidth: 2, opacity: 0.7 },
  { attenuation: 1,  lineWidth: 3, opacity: 1 }
];

const customSiriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios",
  curveDefinition: customDefs
});
```

--------------------------------

### SiriWave File Organization

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/README.md

Overview of the directory structure for the SiriWave project, detailing the location of source files, build outputs, and configuration.

```bash
siriwave/
├── src/
│   ├── index.ts          # Main SiriWave class
│   ├── classic-curve.ts  # ClassicCurve implementation
│   └── ios9-curve.ts     # iOS9Curve implementation
├── dist/
│   ├── siriwave.esm.js   # ES module build
│   ├── siriwave.esm.min.js
│   ├── siriwave.umd.js   # UMD build
│   ├── siriwave.umd.min.js
│   └── types/            # TypeScript declarations
├── package.json
├── tsconfig.json
└── README.md
```

--------------------------------

### Import SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Import the SiriWave class from the 'siriwave' package. This is the first step before creating any SiriWave instances.

```typescript
import SiriWave from "siriwave";
```

--------------------------------

### Rendering Cost Breakdown

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/architecture.md

Illustrates the time complexity of various rendering operations within SiriWave per frame. This helps in understanding performance bottlenecks.

```plaintext
SiriWave.startDrawCycle()         O(1)
  clear()                          O(width * height)
  lerp()                           O(1)
  draw()                           O(curves.length * points.length)
    ClassicCurve.draw()            O(points) per curve
      globalAttFn()                O(1) per point
      sin, arc operations          O(1) per point
    iOS9Curve.draw()               O(noOfCurves * points) per curve
      yRelativePos()               O(noOfCurves) per point
      globalAttFn()                O(1) per point
      sin operations               O(noOfCurves) per point
```

--------------------------------

### Minimal SiriWave Configuration

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Instantiate SiriWave with essential options. This configuration uses all default settings for style, dimensions, speed, amplitude, and color.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave")
});
// Uses all defaults: ios style, 640x200 (from container), speed 0.2, amplitude 1, white color
```

--------------------------------

### Initialize Classic Siriwave

Source: https://github.com/kopiro/siriwave/blob/master/index.html

Initializes the classic Siriwave animation. Ensure the container element exists in the HTML.

```javascript
var SW = new SiriWave({
  container: document.getElementById("container"),
  autostart: true,
});
```

--------------------------------

### Options Type Definition

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Defines the configuration options for the SiriWave constructor. This includes properties for container, style, dimensions, colors, and behavior like autostart and speed.

```typescript
export type Options = {
  container: HTMLElement;
  style?: "ios" | "ios9";
  ratio?: number;
  speed?: number;
  amplitude?: number;
  frequency?: number;
  color?: string;
  cover?: boolean;
  width?: number;
  height?: number;
  autostart?: boolean;
  pixelDepth?: number;
  lerpSpeed?: number;
  curveDefinition?: ICurveDefinition[];
  ranges?: IiOS9Ranges;
  globalCompositeOperation?: GlobalCompositeOperation;
}
```

--------------------------------

### SiriWave Constructor

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

Initializes a new SiriWave instance. You can configure various aspects of the wave animation, such as style, speed, amplitude, and color, through the options object.

```APIDOC
## new SiriWave(options: Options)

### Description
Creates and initializes a new SiriWave instance with the specified configuration.

### Parameters
#### Constructor Options
- **container** (HTMLElement) - Required - DOM element where the canvas will be appended
- **style** ("ios" | "ios9") - Optional - Wave animation style. "ios" is the classic pre-iOS9 style; "ios9" is the fluorescent wave style. Defaults to "ios".
- **ratio** (number) - Optional - Display pixel ratio. Automatically calculated if not provided. Defaults to `window.devicePixelRatio || 1`.
- **speed** (number) - Optional - Animation speed multiplier. Controls how fast the wave oscillates. Defaults to 0.2.
- **amplitude** (number) - Optional - Wave amplitude multiplier. Controls the maximum height of the wave. Defaults to 1.
- **frequency** (number) - Optional - Number of complete waves in the pattern. Only applies to "ios" style. Defaults to 6.
- **color** (string) - Optional - Hexadecimal color code for the wave. Only applies to "ios" style. Accepts shorthand (#F00) and full form (#FF0000). Defaults to "#fff".
- **cover** (boolean) - Optional - If true, the canvas stretches to fill 100% of container width/height. If false, canvas uses explicit pixel dimensions. Defaults to false.
- **width** (number) - Optional - Canvas width in pixels. Automatically reads from container if not provided.
- **height** (number) - Optional - Canvas height in pixels. Automatically reads from container if not provided.
- **autostart** (boolean) - Optional - If true, animation starts immediately after construction. Defaults to true.
- **pixelDepth** (number) - Optional - Distance step in normalized coordinates when drawing curves. Smaller values create smoother curves but reduce performance. Defaults to 0.02.
- **lerpSpeed** (number) - Optional - Linear interpolation speed for smooth property transitions (0 to 1). Controls how quickly speed/amplitude changes animate. Defaults to 0.1.
- **curveDefinition** (ICurveDefinition[]) - Optional - Custom curve definitions to override defaults. Each element defines a wave layer's appearance and behavior. Defaults to null.
- **ranges** (IiOS9Ranges) - Optional - Custom random parameter ranges for iOS9 curve generation. Only applies to "ios9" style. Defaults to null.
- **globalCompositeOperation** (GlobalCompositeOperation) - Optional - Canvas composite operation for blending overlapping waves. Only applies to "ios9" style. Defaults to "lighter".

### Throws
- Throws `Error` with message "Unable to create 2D Context" if canvas 2D context cannot be obtained.
- Throws `Error` when calling `start()` on a disposed instance.
```

--------------------------------

### Initialize SiriWave with iOS9 Style

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Instantiate SiriWave with the 'ios9' style. The curves draw automatically and spawn/despawn wave patterns. Observe the wave amplitude increase for a duration, then gradually fade as waves despawn.

```typescript
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios9"
});
```

--------------------------------

### TypeScript Imports for SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/REFERENCE_GUIDE.md

Demonstrates various ways to import SiriWave components and types in TypeScript projects.

```typescript
// Default export (main class)
import SiriWave from "siriwave";
```

```typescript
// Named exports (curve classes)
import { ClassicCurve, iOS9Curve } from "siriwave";
```

```typescript
// Type imports (recommended)
import type {
  Options,
  IClassicCurveDefinition,
  IiOS9CurveDefinition,
  ICurveDefinition,
  IiOS9Ranges,
  ICurve
} from "siriwave";
```

```typescript
// Combined
import SiriWave, { ClassicCurve, iOS9Curve } from "siriwave";
import type { Options } from "siriwave";
```

--------------------------------

### Responsive SiriWave Design

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Implement responsive SiriWave instances that fill their container and can be manually controlled. Includes an event listener to re-initialize the wave on window resize for adaptive behavior.

```typescript
const container = document.getElementById("wave");
const siriWave = new SiriWave({
  container,
  cover: true,         // Fill container
  autostart: false     // Manual control
});

// Respond to container resize
window.addEventListener("resize", () => {
  siriWave.dispose();
  const newWave = new SiriWave({
    container,
    cover: true
  });
});
```

--------------------------------

### Initialize Single Sub-Curve Parameters (TypeScript)

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/internal-methods.md

Sets up random parameters for a single sub-curve, including phase, amplitude, despawn time, horizontal offset, speed, final amplitude, wavelength, and direction. Uses default ranges unless custom options are provided.

```typescript
private spawnSingle(ci: number): void
```

```typescript
phases[ci] = 0                              // Start phase
amplitudes[ci] = 0                          // Start hidden
despawnTimeouts[ci] = random(500-2000)      // Fade time
offsets[ci] = random(-3 to 3)               // Horizontal shift
speeds[ci] = random(0.5-1.0)                // Speed factor
finalAmplitudes[ci] = random(0.3-1.0)       // Target height
widths[ci] = random(1-3)                    // Wavelength
verses[ci] = random(-1, 1)                  // Direction
```

--------------------------------

### new SiriWave

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Initializes a new SiriWave instance. This is the primary way to create a SiriWave animation on the page.

```APIDOC
## new SiriWave

Initializes a new SiriWave instance.
```

--------------------------------

### Initialize SiriWave with Custom iOS9 Curve Definitions

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Shows how to initialize SiriWave with a custom set of iOS9 curve definitions, allowing for a personalized color scheme.

```typescript
// Or customize the color scheme
const customDefs = [
  { color: "255,255,255", supportLine: true },
  { color: "255, 0, 0" },      // red
  { color: "0, 255, 0" },      // green
  { color: "0, 0, 255" }       // blue
];

const customSiriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios9",
  curveDefinition: customDefs
});
```

--------------------------------

### Initialize iOS9+ Siriwave

Source: https://github.com/kopiro/siriwave/blob/master/index.html

Initializes the iOS9+ style Siriwave animation. Specify the 'ios9' style and ensure the container element exists.

```javascript
var SW9 = new SiriWave({
  style: "ios9",
  container: document.getElementById("container-9"),
  autostart: true,
});
```

--------------------------------

### Configure SiriWave Frequency (iOS Style)

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/configuration.md

Adjust the number of complete waves in the pattern for the iOS style. Higher values create a tighter pattern.

```typescript
const siriWave1 = new SiriWave({
  container: element,
  style: "ios",
  frequency: 8
});

// Default frequency
const siriWave2 = new SiriWave({
  container: element,
  style: "ios",
  frequency: 6
});

// Fewer waves, looser pattern
const siriWave3 = new SiriWave({
  container: element,
  style: "ios",
  frequency: 4
});
```

--------------------------------

### Initialize SiriWave with Default iOS9 Curve

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Demonstrates initializing SiriWave using the default iOS9 curve definitions. The `curveDefinition` option can be omitted as it defaults to `iOS9Curve.getDefinition()` when `style` is set to 'ios9'.

```typescript
// Get default curve definitions
const defaultDefs = iOS9Curve.getDefinition();

// Use defaults with SiriWave
const siriWave = new SiriWave({
  container: document.getElementById("wave-container"),
  style: "ios9"
  // curveDefinition defaults to iOS9Curve.getDefinition()
});
```

--------------------------------

### Import ClassicCurve

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/classic-curve.md

Import the ClassicCurve class from the siriwave library. This is required to use the class.

```typescript
import { ClassicCurve } from "siriwave";
```

--------------------------------

### Total Rendering Cost Formula

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/architecture.md

Provides the overall time complexity formula for rendering a single frame in SiriWave, considering canvas dimensions and curve/point counts.

```plaintext
O(width * height + curves * points)
```

--------------------------------

### Import iOS9Curve

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/ios9-curve.md

Import the iOS9Curve class from the siriwave library.

```APIDOC
## Import

```typescript
import { iOS9Curve } from "siriwave";
```
```

--------------------------------

### Implementing Custom SiriWave Curves

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/architecture.md

For advanced visual customization, implement the `ICurve` interface and assign an instance to the `curves` property. This allows for custom rendering logic.

```typescript
class CustomCurve implements ICurve {
  draw() { /* custom rendering */ }
}

const sw = new SiriWave({ ... });
sw.curves = [new CustomCurve()];
```

--------------------------------

### Include SiriWave via CDN

Source: https://github.com/kopiro/siriwave/blob/master/README.md

Use this script tag to include the UMD package of SiriWave directly in your HTML for browser usage.

```html
<script src="https://unpkg.com/siriwave/dist/siriwave.umd.min.js"></script>
```

--------------------------------

### SiriWave Instance Properties

Source: https://github.com/kopiro/siriwave/blob/master/_autodocs/api-reference/siriwave-main-class.md

These properties provide access to the current state and configuration of a SiriWave instance after it has been created.

```APIDOC
### Instance Properties

- **`opt`** (Options): The configuration options passed to the constructor.
- **`phase`** (number): Current phase of the wave animation (0 to 2π). Increments each frame and controls wave position.
- **`run`** (boolean): Boolean flag indicating if animation is currently running.
- **`curves`** (ICurve[]): Array of curve objects being animated and rendered.
- **`speed`** (number): Current animation speed (interpolated if being transitioned).
- **`amplitude`** (number): Current wave amplitude (interpolated if being transitioned).
- **`width`** (number): Canvas width in pixels (includes pixel ratio scaling).
- **`height`** (number): Canvas height in pixels (includes pixel ratio scaling).
- **`heightMax`** (number): Maximum height available for a single wave (height/2 - 6 pixels).
- **`color`** (string): RGB color string for classic iOS waves.
- **`canvas`** (HTMLCanvasElement | null): The canvas DOM element. Becomes null after dispose().
- **`ctx`** (CanvasRenderingContext2D): 2D rendering context of the canvas.
```