Sounds and music

The sound module is a wrapper around the PixiJS Sound library. It provides a simple interface for playing sounds and saves the current state at each step.

It is composed of the following elements, which will be referenced later:

• sound (manager) is the controller of the entire audio system. It is used to manage channels, start and control musical media, and retrieve information or modify sound assets. You can set values to adjust the overall audio level. These settings are not stored in save files and are mainly intended for game settings.
• channels is a sub-level of the sound manager and can be seen as a container. It is used to contain, start, and manage musical media. You can set values to affect only the contained media. These settings are not stored in save files and are mainly intended for game settings.
• media are instances of a sound that has been started. You can set values that apply only to themselves. All settings applied to them are saved in the game save. These settings are mainly intended to be modified during gameplay. They are contained within a channel in a one-to-many relationship. Each media has a unique alias.
• assets (sound assets), as the name suggests, are the assets used during the game to play sounds. You can set values to influence all media that use this asset. These settings are not saved and are mainly intended to be configured during game initialization when loading assets.

import { narration, newLabel, sound } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await sound.play("sfx_whoosh", { delay: 0.1 });
        await sound.play("bgm_cheerful", { loop: true, channel: "bgm" });
        narration.dialogue = "Hello, I'm a cheerful background music that will loop forever until you stop me.";
    },
    () => {
        sound.pause("bgm_cheerful");
        narration.dialogue = "I'm paused, but I can be resumed.";
    },
    () => {
        sound.resume("bgm_cheerful");
        narration.dialogue = "I'm back!";
    },
]);

Initialize

First of all, you need to define the asset matrix exactly as with other components. After that, it is recommended to load sounds at the start of the game using the functions provided by sound.

import { Assets, sound } from "@drincs/pixi-vn";
import manifest from "../assets/manifest";

/**
 * Define all the assets that will be used in the game.
 * This function will be called before the game starts.
 * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
 */
export async function defineAssets() {
    await Assets.init({ manifest });

    // The audio bundle will be loaded in the background, so it will be available when needed, but it won't block the game start.
    sound.backgroundLoadBundle("audio"); 
}

It is also recommended to define channels immediately after game initialization. During the definition of channels, you can configure their settings, which are all intuitive and based on PixiJS Sound, except for:

• background (Optional): this is a boolean value that can be used to define channels intended for background sounds such as music or ambient audio. Unlike other sounds, they will not be stopped between narrative steps.

import { Game, sound } from "@drincs/pixi-vn";

Game.init(body, {
    // ...
}).then(() => {
    sound.addChannel("bgm", { background: true });
    sound.addChannel("sfx");
    sound.defaultChannelAlias = "sfx";
});

Play

The basic functionality is to start a sound (asset). This can be done using the play function. The play function generates a media instance that you can interact with to control the produced sound.

This function has the following parameters:

• alias: The alias to identify the media.
• soundUrl (Optional): The URL or path. If you have initialized the asset matrix, you can use the alias of the sound. If you don't provide the URL, then the alias is used as the URL.
• options (Optional): The options for the media.
  • delay: The delay before the sound starts, in seconds.
  • loop: Override default loop, default to the Sound's loop setting.
  • speed: Override default speed, default to the Sound's speed setting.
  • volume: Override default volume, default to the Sound's volume setting.
  • start: Start time offset in seconds.
  • end: End time in seconds.
  • muted: If sound instance is muted by default.
  • filters: Filters that apply to play. Only supported with WebAudio.
  • channel: The alias of the channel to which the media will be assigned. If not specified, it will be assigned to sound.defaultChannelAlias.

Pause and resume

There are various ways to pause individual or multiple media.

Edit

It is possible to edit almost all settings at any time for different purposes.

Stop

To stop a sound, you can use the stop function.

Filters

Filters are elements that allow advanced customization of sounds.