Use typedoc to generate documentation which should be auto-built into…

… a GH-pages website

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master  
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '18'
+
+    - name: Install Dependencies
+      run: npm install
+
+    - name: Generate Documentation
+      run: npm run docs
+
+    - name: Deploy
+      uses: JamesIves/[email protected]
+      with:
+        branch: gh-pages
+        folder: docs

README.md

@@ -1,111 +1,51 @@
-Cacophony is a comprehensive and versatile audio library for TypeScript, utilizing the Web Audio API to streamline audio management in sophisticated applications. At the heart of Cacophony lies the creation and manipulation of key elements: `Sound`, `Playback`, `Group`, and now `MicrophoneStream` for live audio input.
 
-- A `Sound` represents a distinct audio source, derived from an `AudioBuffer` or a URL string pointing to an audio file, with advanced filter management.
-- A `Playback` refers to the act of playing a `Sound`, with additional properties such as position in a 3D audio scene, gain-node for volume control, and methods for fading audio in and out.
-- A `Group` encapsulates multiple `Sound` instances to handle them as one entity, allowing for synchronous control of playback.
-- A `MicrophoneStream` captures live audio input from the user's microphone, providing real-time audio streaming capabilities. Use `getMicrophoneStream` to access this feature.
+## Cacophony: Advanced Browser Audio Library
 
-## Key Features
+Cacophony is an intuitive and powerful audio library designed for the modern web. It's built to simplify audio management within browser-based applications, offering a straightforward interface to the Web Audio API. Cacophony is ideal for projects that require detailed audio control, from simple sound playback to complex audio processing and 3D audio positioning.
 
-- Multiple Audio Sources: Seamlessly manage buffers, URLs, groups of sounds, playbacks, and live microphone input.
-- Comprehensive Audio Control: Play, stop, pause, resume, loop (finite or infinite), and adjust volume with ease.
-- 3D Audio Positioning: Precisely position audio sources in a 3D space for an immersive experience.
-- Advanced Audio Filtering: Add, remove, or apply filters directly to audio sources for enhanced sound quality.
-- Dynamic Volume Control: Mute, unmute, and adjust volume globally or individually, with fade-in and fade-out effects.
+## Key Features
 
-## Quick Installation
+- **Rich Audio Source Management**: Handle audio sources from `AudioBuffer`, URL strings, or user's microphone with ease.
+- **Detailed Audio Control**: Comprehensive control over audio playback including play, stop, pause, resume, and loop.
+- **3D Audio Positioning**: Create immersive audio experiences by positioning sounds in a three-dimensional space.
+- **Advanced Audio Effects**: Apply and manage a variety of audio filters for enhanced sound quality.
+- **Dynamic Volume and Muting**: Global and individual volume control, complete with smooth fade-in and fade-out effects.
+- **Live Audio Input**: Capture and process live audio input from the user's microphone.
 
-Cacophony is provided as a regular NPM module. Install it using:
+## Installation
 
 ```bash
-$ npm install cacophony
+npm install cacophony
 ```
 
-## Straightforward Usage
-
-Utilizing Cacophony in the codebase is effortless, demonstrated below:
+## Quick Start
 
 ```typescript
-import { Cacophony } from 'cacophony-ts';
+import { Cacophony } from 'cacophony';
 
 async function playSampleSound() {
   const cacophony = new Cacophony();
-  const sound = await cacophony.createSound('path/to/your/audio/file.mp3');
-
+  const sound = await cacophony.createSound('path/to/audio.mp3');
   sound.play();
-  sound.position = [1, 1, 1]; // Position the sound in 3D space
+  sound.position = [1, 1, 1]; // Set sound position in 3D space
 }
 
 playSampleSound();
 ```
 
-## Comprehensive Documentation
-
-### Main Class: `Cacophony`
-
-The centerpiece of the library delivers methods for creating sounds, managing global volumes, and more.
-
-#### Method: `createSound(bufferOrUrl: AudioBuffer | string): Promise<Sound>`
-
-Crafts a `Sound` instance using either an `AudioBuffer` or a URL string leading to the desired audio file.
-
-#### Method: `createGroup(sounds: Sound[]): Promise<Group>`
-
-Creates a `Group` entity from an array of `Sound` instances.
-
-#### Method: `createGroupFromUrls(urls: string[]): Promise<Group>`
-
-Forms a `Group` instance from an array of URLs directing to the desired audio files. This method does not require a `type` parameter as `createSound` does.
-
-#### Method: `createBiquadFilter(type: BiquadFilterType): BiquadFilterNode`
+## Detailed API Documentation
 
-Generates a `BiquadFilterNode` ready to be applied to sounds.
+For a complete overview of all functionalities, classes, and methods, please refer to our [detailed documentation](https://[your-username].github.io/[your-repo-name]/).
 
-#### Method: `pause()`
+## Additional Highlights
 
-Halts all active audio.
+- **Streaming Audio**: Stream live audio directly from a URL.
+- **Volume Transitions**: Employ `fadeIn` and `fadeOut` for nuanced volume control.
 
-#### Method: `resume()`
+## Contributing
 
-Resumes all paused audio.
-
-#### Method: `stopAll()`
-
-Complete cessation of all audio, irrespective of their current states.
-
-#### Method: `setGlobalVolume(volume: number)`
-
-Adjusts the global volume to the passed value.
-
-#### Method: `mute()`
-
-Silences all audio by setting the global volume to 0.
-
-#### Method: `unmute()`
-
-Resumes audio by restoring the global volume to its preceding value.
-
-### Unified Methods Across Sound Sources
-
-All classes representing sound sources (`Sound`, `Playback`, `Group`, `MicrophoneStream`) and the `BaseSound` interface offer the following methods for a consistent interface and user-friendly experience:
-
-- `play()`: Initiates playback of the sound.
-- `seek(time: number)`: Seeks the current playback to the specified time in seconds (not applicable to `MicrophoneStream`).
-- `stop()`: Stops the sound and resets playback.
-- `pause()`: Pauses the sound without resetting playback.
-- `resume()`: Resumes paused sound.
-- `addFilter(filter: BiquadFilterNode)`: Adds a filter to the sound.
-- `removeFilter(filter: BiquadFilterNode)`: Removes a filter from the sound.
-- `position`: A tuple `[x: number, y: number, z: number]` representing the position of the sound in 3D space, with both getter and setter (not applicable to `MicrophoneStream`).
-- `loop(loopCount?: LoopCount)`: Sets the loop count for the sound, which can be a finite number or 'infinite'.
-- `fadeIn(time: number, fadeType?: FadeType)`: Gradually increases the volume of the sound over the specified time.
-- `fadeOut(time: number, fadeType?: FadeType)`: Gradually decreases the volume of the sound over the specified time.
-- `cleanup()`: Cleans up resources associated with the sound, removing any associated filters and disconnecting audio nodes (applicable to `Playback` and `MicrophonePlayback`).
+We welcome contributions! If you're interested in helping improve Cacophony, please check out our [contribution guidelines](CONTRIBUTING.md).
 
 ## License
 
-Cacophony is freely available for incorporation into your projects under the [MIT License](LICENSE.txt).
-## Additional Features
-
-- Streaming Audio: Create a stream from a URL to play live audio with `createStream`.
-- Dynamic Volume Control: Use `fadeIn` and `fadeOut` methods for smooth transitions in volume.
+Cacophony is open-source software licensed under the [MIT License](LICENSE.txt)

package.json

@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "build": "npm run clean && tsc --build",
+    "docs": "typedoc --out docs src",
     "clean": "tsc --build --clean",
     "prepublishOnly": "npm run build",
     "test": "jest",
@@ -30,6 +31,7 @@
     "jest": "^29.7.0",
     "standardized-audio-context-mock": "^9.6.31",
     "ts-jest": "^29.1.1",
+    "typedoc": "^0.25.4",
     "typescript": "^5.3.2"
   },
   "jest": {
@@ -39,4 +41,4 @@
   "dependencies": {
     "standardized-audio-context": "^25.3.60"
   }
-}
+}