Sound Manager

https://github.com/xelnae-r/sound-manager
Admin
Sound Manager is a Roblox sound-management library built with Roblox-TS, designed to simplify sound...
Tokens:6,072
Snippets:69
Trust Score:6.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Clone and Run Sound-Manager Template

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/quick-start/examples.md

Clone the repository, install dependencies, and start the development server. Ensure you have Node.js, Roblox-TS, and Rojo installed.

```bash
git clone https://github.com/dev-lukas0/Sound-Manager-Template.git

cd Sound-Manager-Template
npm install
npm run watch
rojo serve
```

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

### Install Sound-Manager with npm

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/quick-start/installation.md

Use this command to install the Sound-Manager package in your project via npm.

```bash
npm install @rbxts/sound-manager
```

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

### Install Sound-Manager with yarn

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/quick-start/installation.md

Use this command to install the Sound-Manager package in your project via yarn.

```bash
yarn add @rbxts/sound-manager
```

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

### Create an Audio Listener

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-audio-listener.md

Creates an AudioListener associated with the current camera. This is a basic usage example.

```typescript
const newAudioListener = createAudioListener(Workspace.CurrentCamera);
```

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

### Play a sound from the SoundRegistry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/quick-start/index.md

Use the SoundRegistry instance to play sounds by their defined keys. This example plays the 'backgroundMusic'.

```typescript
soundRegistry.play("backgroundMusic"); // Plays the background music
```

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

### Get Sound Properties

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/developer-tools.md

Retrieve the properties of a specific sound by its name. Useful for inspecting sound settings and configurations.

```typescript
const Sounds = {
    TestSound: {
        id: "rbxassetid://4714389545",
        volume: 1,
        loop: false,
    },
} as const;

const soundProps = Developer_Tools.getSoundProperties<typeof Sounds>("TestSound", sounds);
```

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

### Sound Manager Developer Tools

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Utilize developer tools for debugging sound states and inspecting configurations. Functions include getting total sound counts, listing playing sounds, and retrieving sound properties.

```typescript
import { Developer_Tools, createSoundRegistry } from "@rbxts/sound-manager";

const Sounds = createSoundRegistry({
    TestSound: {
        id: "rbxassetid://4714389545",
        volume: 1,
        loop: false,
    },
    AmbientSound: {
        id: "rbxassetid://5555555555",
        volume: 0.5,
        loop: true,
    },
});

// Get total count of loaded sounds (legacy + spatial)
const totalCount = Developer_Tools.getTotalSoundCount();
print(`Total loaded sounds: ${totalCount}`);

// Get list of currently playing sounds
const playingSounds = Developer_Tools.getCurrentPlayingSounds();
for (const soundName of playingSounds) {
    print(`Playing: ${soundName}`);
}

// Get properties of a specific sound from definitions
const soundDefinitions = {
    TestSound: {
        id: "rbxassetid://4714389545",
        volume: 1,
        loop: false,
    },
} as const;

const props = Developer_Tools.getSoundProperties<typeof soundDefinitions>("TestSound", soundDefinitions);
print(`Sound ID: ${props.id}`);
print(`Volume: ${props.volume}`);
print(`Looped: ${props.loop}`);
```

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

### Get Total Sound Count

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/developer-tools.md

Use this function to get the total number of loaded sounds. Helps track the number of sounds in your project.

```typescript
const totalSounds = Developer_Tools.getTotalSoundCount();
```

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

### Get Currently Playing Sounds

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/developer-tools.md

Use this function to retrieve a list of all currently playing sounds. Useful for debugging and monitoring sound playback.

```typescript
const playingSounds = Developer_Tools.getCurrentPlayingSounds();
```

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

### Create a SoundRegistry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/quick-start/index.md

Initialize a SoundRegistry with your sound definitions. Ensure the 'id' property correctly points to your sound assets.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

const sounds = {
    backgroundMusic: {
        id: "rbxassetid://1234567890",
        volume: 0.5,
        looped: true,
    },
    jumpSound: {
        id: "rbxassetid://0987654321",
        volume: 1.0,
        looped: false,
    },
} as const;

export const soundRegistry = createSoundRegistry(sounds);
```

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

### Create Sound Registry Instance

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-registry.md

Instantiate a Sound-Registry using `createSoundRegistry` with your sound definitions.

```typescript
const soundRegistry = createSoundRegistry(sounds);
```

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

### Create an Audio Listener with Name

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-audio-listener.md

Creates an AudioListener with a specified name, linked to the current camera. Ensure necessary services and functions are imported.

```typescript
import { Workspace } from "@rbxts/services";
import { createAudioListener } from "@rbxts/sound-manager";

export const newAudioListener = createAudioListener(Workspace.CurrentCamera, "Test");
```

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

### Create Sound Registry

Source: https://github.com/xelnae-r/sound-manager/blob/master/README.md

Use `createSoundRegistry` to define and manage your game's sounds. Each sound can have properties like id, volume, and loop.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

const Sounds = createSoundRegistry({
    SCP096: {
        id: "rbxassetid://4714389545",
        volume: 1,
        loop: false,
    },

    Test: {
        id: "rbxassetid://17771398985",
        volume: 1,
        loop: true,
    }
});
```

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

### Create Audio Listener

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Sets up an AudioListener for spatial audio. Can be attached to a Camera, BasePart, or Model. Provides access to the underlying listener, output, and wire components. Remember to destroy the listener when no longer needed.

```typescript
import { Workspace } from "@rbxts/services";
import { createAudioListener } from "@rbxts/sound-manager";

// Create audio listener attached to player camera
const audioListener = createAudioListener(Workspace.CurrentCamera!, "PlayerListener");

// Audio listener provides access to underlying components
if (audioListener) {
    print(`Listener created: ${audioListener.listener.Name}`);
    print(`Output device: ${audioListener.output.Name}`);
    print(`Wire connection: ${audioListener.wire.Name}`);
}

// Create listener on a BasePart (e.g., player head)
const playerHead = game.Workspace.WaitForChild("PlayerHead") as BasePart;
const headListener = createAudioListener(playerHead, "HeadListener");

// Create listener on a Model
const characterModel = game.Workspace.WaitForChild("Character") as Model;
const modelListener = createAudioListener(characterModel);

// Destroy the audio listener when no longer needed
audioListener?.destroy();
```

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

### Play a Sound

Source: https://github.com/xelnae-r/sound-manager/blob/master/README.md

Use the `play` method on the sound registry to play a specific sound by its key. Ensure the sound has been defined in the registry.

```typescript
Sounds.play("SCP096");
```

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

### createSoundRegistry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-registry.md

Creates a Sound-Registry from a record of sound definitions.

```APIDOC
## createSoundRegistry

### Description
`createSoundRegistry` lets you create a Sound-Registry to manage sounds in your Roblox-TS project.

### Method
`createSoundRegistry(definitions: Record<string, SoundOptions>)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **definitions** (Record<string, SoundOptions>) - Required - A record of sound definitions.

### Request Example
```json
{
  "backgroundMusic": {
    "id": "rbxassetid://1234567890",
    "volume": 0.5,
    "looped": true
  },
  "jumpSound": {
    "id": "rbxassetid://0987654321",
    "volume": 1.0,
    "looped": false
  }
}
```

### Response
#### Success Response (200)
- **soundRegistry** (SoundRegistry) - The created Sound-Registry object.

#### Response Example
```json
{
  "soundRegistry": { ... }
}
```
```

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

### Define Sounds for Registry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-registry.md

Define your sounds with their asset IDs, volume, and loop settings. This record is then passed to `createSoundRegistry`.

```typescript
const sounds = {
    backgroundMusic: {
        id: "rbxassetid://1234567890",
        volume: 0.5,
        looped: true,
    },
    jumpSound: {
        id: "rbxassetid://0987654321",
        volume: 1.0,
        looped: false,
    },
} as const;

export const soundRegistry = createSoundRegistry(sounds);
```

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

### Create Audio Listener

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-audio-listener.md

The `createAudioListener` function allows you to create and manage an AudioListener. This is crucial for proper 3D spatial audio implementation.

```APIDOC
## createAudioListener

### Description
Creates an Audio-Listener.

### Method
`createAudioListener`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **parent** (BasePart | Camera | Model) - Required - The parent object for the audio listener.
- **name** (string) - Optional - The name for the audio listener.

### Request Example
```typescript
import { Workspace } from "@rbxts/services";
import { createAudioListener } from "@rbxts/sound-manager";

const newAudioListener = createAudioListener(Workspace.CurrentCamera, "Test");
```

### Response
#### Success Response (200)
- **AudioListenerHandle | undefined**: Returns a handle to the created AudioListener or undefined if creation failed.

#### Response Example
```json
{
  "example": "AudioListenerHandle"
}
```
```

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

### Create Sound Category Registry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-category-registry.md

Instantiate a Sound-Category-Registry using provided sound categories. Ensure the 'soundCategories' variable is defined before use.

```typescript
const soundCategoryRegistry = createSoundCategoryRegistry(soundCategories);
```

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

### Create and Use a Sound Registry

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Defines and manages individual sounds with type safety. Supports 2D and 3D audio, preloading, playback control, fading, and event handling. Ensure sounds are preloaded before playback for optimal performance.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

// Define sound configurations
const Sounds = createSoundRegistry({
    BackgroundMusic: {
        id: "rbxassetid://1234567890",
        volume: 0.5,
        loop: true,
        playbackSpeed: 1,
    },
    JumpSound: {
        id: "rbxassetid://0987654321",
        volume: 1,
        loop: false,
    },
    ExplosionSound: {
        id: "rbxassetid://5555555555",
        volume: 0.8,
        loop: false,
    },
});

// Preload all sounds at game start
Sounds.preloadAll();

// Play a sound
Sounds.play("BackgroundMusic");

// Play spatial sound attached to game objects
const emitters = [game.Workspace.WaitForChild("Part1") as BasePart];
Sounds.play("ExplosionSound", { emitters });

// Stop a sound
Sounds.stop("BackgroundMusic");

// Fade in a sound over 2 seconds to volume 0.8
Sounds.fadeIn("BackgroundMusic", 2, 0.8);

// Fade out a sound over 3 seconds
Sounds.fadeOut("BackgroundMusic", 3);

// Check if a sound is playing
const isPlaying = Sounds.isPlaying("BackgroundMusic");
print(`Background music playing: ${isPlaying}`);

// Set volume for specific sound
Sounds.setVolume("BackgroundMusic", 0.3);

// Set global volume for all sounds
Sounds.setGlobalVolume(0.5);

// Set time position
Sounds.setTimePosition("BackgroundMusic", 10);

// Reset sound to beginning
Sounds.reset("BackgroundMusic");

// Execute callback when sound ends
Sounds.onEnd("JumpSound", () => {
    print("Jump sound finished!");
});

// Stop all sounds with reset
Sounds.stopAll(true);

// Destroy a sound instance
Sounds.destroy("JumpSound");

```

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

### SoundOptions Interface for Sound Definitions

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Define sounds with comprehensive configuration options including ID, volume, loop, playback speed, and spatial audio settings.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

// Full sound configuration options
const Sounds = createSoundRegistry({
    FullyConfiguredSound: {
        id: "rbxassetid://1234567890",  // Required: Roblox asset ID
        volume: 0.75,                    // Optional: Volume level (default: 1)
        loop: true,                      // Optional: Loop playback (default: false)
        playbackSpeed: 1.2,              // Optional: Playback speed multiplier (default: 1)
        spatial: {
            attenuation: 0.5,
            directional: true,
        },
    },
    MinimalSound: {
        id: "rbxassetid://0987654321",  // Only id is required
    },
});
```

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

### createSoundCategoryRegistry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-category-registry.md

Creates a Sound-Category-Registry from a record of sound definitions. This is useful for organizing numerous sounds into manageable groups.

```APIDOC
## createSoundCategoryRegistry

### Description
Creates a Sound-Category-Registry from a record of sound definitions.

### Method
`createSoundCategoryRegistry`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **definitions** (Record<string, CategoryOptions>) - Required - A record where keys are sound category names and values are `CategoryOptions` objects defining the sounds within that category.

### Request Example
```json
{
  "music": {
    "category": "Music",
    "sounds": {
      "backgroundMusic": {
        "id": "rbxassetid://1234567890",
        "volume": 0.5,
        "looped": true
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **soundCategoryRegistry** (SoundCategoryRegistry) - The created Sound-Category-Registry object.

#### Response Example
```json
{
  "soundCategoryRegistry": { ... }
}
```
```

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

### Define and Create Sound Category Registry

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/create-sound-category-registry.md

Define sound categories with their options and then create a Sound-Category-Registry. This is useful for organizing many sounds into logical groups.

```typescript
const categories = {
    music: {
        category: "Music",
        sounds: {
            backgroundMusic: {
                id: "rbxassetid://1234567890",
                volume: 0.5,
                looped: true,
            },
        },
    }
} as const;

export const soundCategoryRegistry = createSoundCategoryRegistry(categories);
```

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

### Create Sound Category Registry

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Organizes sounds into categories for management. Preload, play, stop, and control volume for entire categories or individual sounds within them. Supports spatial audio playback with emitters.

```typescript
import { createSoundCategoryRegistry } from "@rbxts/sound-manager";

// Define sound categories
const SoundCategories = createSoundCategoryRegistry({
    Music: {
        category: "Music",
        sounds: {
            MainTheme: {
                id: "rbxassetid://1111111111",
                volume: 0.5,
                loop: true,
            },
            BattleTheme: {
                id: "rbxassetid://2222222222",
                volume: 0.6,
                loop: true,
            },
        },
    },
    SFX: {
        category: "SFX",
        sounds: {
            Footstep: {
                id: "rbxassetid://3333333333",
                volume: 0.8,
                loop: false,
            },
            DoorOpen: {
                id: "rbxassetid://4444444444",
                volume: 1.0,
                loop: false,
            },
        },
    },
});

// Preload all categories
SoundCategories.preloadAllCategories();

// Preload specific category
SoundCategories.preloadCategory("Music");

// Play all sounds in a category
SoundCategories.playCategory("Music");

// Play category with spatial audio
const emitters = [game.Workspace.WaitForChild("SpeakerPart") as BasePart];
SoundCategories.playCategory("SFX", { emitters });

// Play a specific sound from a category
SoundCategories.playSoundFromCategory("SFX", "Footstep");

// Stop all sounds in a category
SoundCategories.stopCategory("Music");

// Stop all categories
SoundCategories.stopAllCategories();

// Set volume for a category
SoundCategories.setCategoryVolume("Music", 0.3);

// Set global volume for all categories
SoundCategories.setGlobalCategoryVolume(0.5);

// Check if a category is playing
const isPlaying = SoundCategories.isCategoryPlaying("Music");
print(`Music category playing: ${isPlaying}`);

// Fade in a category over 2 seconds
SoundCategories.fadeInCategory("Music", 2, 0.8);

// Fade out a category over 3 seconds
SoundCategories.fadeOutCategory("Music", 3);

// Reset category time positions
SoundCategories.resetCategory("Music");

// Reset all categories
SoundCategories.resetAllCategories("Music");

// Execute callback when all sounds in category end
SoundCategories.onCategoryEnd("SFX", () => {
    print("All SFX sounds finished!");
});
```

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

### Preload Spatial Sounds with Sound Manager

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Preload spatial sounds to prevent audio latency. Use `preloadSpatial` for single sounds or `preloadAllSpatial` for multiple sounds with their emitters.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

const Sounds = createSoundRegistry({
    Footstep: {
        id: "rbxassetid://1111111111",
        volume: 0.8,
        loop: false,
    },
    Gunshot: {
        id: "rbxassetid://2222222222",
        volume: 1,
        loop: false,
    },
    Explosion: {
        id: "rbxassetid://3333333333",
        volume: 0.9,
        loop: false,
    },
});

// Preload single spatial sound
const playerFeet = game.Workspace.WaitForChild("PlayerFeet") as BasePart;
Sounds.preloadSpatial("Footstep", [playerFeet]);

// Preload multiple spatial sounds with their emitters
const gunBarrel = game.Workspace.WaitForChild("GunBarrel") as BasePart;
const explosionPoint = game.Workspace.WaitForChild("ExplosionPoint") as BasePart;

Sounds.preloadAllSpatial({
    Footstep: [playerFeet],
    Gunshot: [gunBarrel],
    Explosion: [explosionPoint],
});
```

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

### Sound-Registry API

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/index.md

Sound-Registry is the core of Sound-Manager. It allows you to define, create, and manage sounds in your Roblox-TS Project.

```APIDOC
## Sound-Registry API

### Description
Manages sounds in your Roblox-TS Project.

### Method
N/A (This is a constructor/factory function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
const sounds = {
    backgroundMusic: {
        id: "rbxassetid://1234567890",
        volume: 0.5,
        looped: true,
    },
    jumpSound: {
        id: "rbxassetid://0987654321",
        volume: 1.0,
        looped: false,
    },
} as const;

export const soundRegistry = createSoundRegistry(sounds);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Spatial Sound Handle Control

Source: https://context7.com/xelnae-r/sound-manager/llms.txt

Manages individual spatial sound playback. The returned handle allows for granular control over playback, fading, time position, playback speed, and event callbacks. Ensure to destroy the handle when finished to prevent memory leaks.

```typescript
import { createSoundRegistry } from "@rbxts/sound-manager";

const Sounds = createSoundRegistry({
    Ambience: {
        id: "rbxassetid://9999999999",
        volume: 0.7,
        loop: true,
        playbackSpeed: 1,
    },
});

// Get spatial sound handle
const emitters = [
    game.Workspace.WaitForChild("TreePart") as BasePart,
    game.Workspace.WaitForChild("WaterPart") as BasePart,
];

const handle = Sounds.play("Ambience", { emitters });

if (handle) {
    // Control playback
    handle.play();
    handle.stop();

    // Fade effects
    handle.fadeIn?.(2, 0.8);  // Fade in over 2 seconds to volume 0.8
    handle.fadeOut?.(3);      // Fade out over 3 seconds

    // Check playback state
    const isPlaying = handle.playing();
    print(`Spatial sound playing: ${isPlaying}`);

    // Set time position
    handle.setTimePosition(5);

    // Adjust playback speed
    handle.setPlayBackSpeed(1.5);

    // Register callback when sound ends
    handle.played(() => {
        print("Spatial sound finished playing!");
    });

    // Clean up when done
    handle.destroy();
}
```

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

### Sound-Categories API

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/reference/index.md

Sound-Categories allow you to group sounds together and manage them as a single unit, useful for organizing many sounds.

```APIDOC
## Sound-Categories API

### Description
Organizes and manages sounds by grouping them into categories.

### Method
N/A (This is a constructor/factory function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
const categories = {
    music: {
        category: "Music",
        sounds: {
            backgroundMusic: {
                id: "rbxassetid://1234567890",
                volume: 0.5,
                looped: true,
            },
        },
    }
} as const;

export const soundCategoryRegistry = createSoundCategoryRegistry(categories);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Play Spatial Sound Category

Source: https://github.com/xelnae-r/sound-manager/blob/master/docs/docs/spatial.md

Plays a specified sound category using spatial audio emitters. Ensure emitters are correctly defined and available in the workspace.

```typescript
const emitters: BasePart[] = [
    game.Workspace.WaitForChild("Part1") as BasePart,
];

SoundCategories.playCategory("SCP096", { emitters });
```
Tokens:
Raw