Short Clips

Short Clips

Important

Do not use short clips for long files. Stream them instead.

When you want to play short sounds (e.g. sound effects), it's best to use short clips instead of streaming them. Reading and seeking is faster when audio files are in memory.

The ShortClipCache class stores these clips after loading them. Lookups are case-insensitive (will match regardless of case).

Extension methods help to play the clips back.

The ClipName struct can be implicitly be converted from a string, so you can pass a string to methods that have this parameter.

• UseShortClip replaces the AudioPlayer's SampleProvider with the clip
• MixShortClip adds a clip to the player's Mixer
• EnqueueShortClip plays the clip after the previous input (queues it)

Example

Register clips when your plugin loads.

If you have to dynamically load clips on a specific event, there might be some lag due to reading files to the end.

using SecretLabNAudio.Core.FileReading;

// the file name without the extension will be the clip's name
ShortClipCache.AddFromFile("/path/to/clip.wav");
ShortClipCache.AddFromFile("/path/to/clip2.wav");

// custom clip name
ShortClipCache.AddFromFile("/path/to/clip3.wav", "CustomName");

// keep the file extension
ShortClipCache.AddFromFile("/path/to/clip4.wav", false);

Play the clips one by one:

using SecretLabNAudio.Core.Extensions;
using SecretLabNAudio.Core.Pools;

AudioPlayerPool.RentGloballyAudible()
    .UseShortClip("clip", 0.8f) // 80% volume
    .EnqueueShortClip("clip2") // plays after clip.wav
    .EnqueueShortClip("customName") // plays after clip2.wav
    .EnqueueShortClip(("clip4.wav", false)) // plays after clip3.wav 
    .PoolOnEnd();

Tip

See also: supported file formats

Loading Short Clips

Use the methods in the ShortClipCache class to add clips from files. Clips will automatically be mixed down and resampled, no need to convert them to 48000 Hz mono Ogg Vorbis files.

• AddAllFromDirectory adds all clips from a specific directory
• AddAllFromPaths adds clips of the given paths, with an optional base directory
• AddFromFile loads a single clip
• AddFromEmbeddedResource extracts a manifest resource from the given assembly

Most methods have a ClipName overload - you can pass a string to them directly. If you don't want to trim the extensions when adding the file, pass trimExtension: false or create a ClipName struct with the matching property.

Pass a maxDuration parameter to prevent adding clips longer than a threshold.

Tip

See also: adding clips with FFmpeg

Embedded Resources

Embedded resources are used to store assets inside the DLL. However, if a consumer wants to modify the assets, they must compile the project themselves. For better customizability, consider reading files from a directory.

A plugin's folder structure might look like this:

Assets/
 - sus.wav 
 - mogus.ogg
EventHandlers.cs
MyPlugin.cs
MyPlugin.csproj

Specify resources in the csproj

<ItemGroup>
    <!-- all wave files directly in the Audio directory -->
    <EmbeddedResource Include="Audio/*.wav" />
    <!-- includes nested folders in Assets -->
    <EmbeddedResource Include="Assets/**.mp3" />
</ItemGroup>
<!-- specify files individually -->
<ItemGroup>
    <EmbeddedResource Include="Audio/sus.wav" />
    <EmbeddedResource Include="Audio/mogus.ogg" />
</ItemGroup>

This will create embedded resources prefixed with the root namespace + the folder structure joined with .

• Root namespace is MyPlugin
• sus.wav file in the Audio directory
• Resource name becomes MyPlugin.Audio.sus.wav

To add short clips to the cache from embedded resources, use the AddFromEmbeddedResource or AddAllFromEmbeddedResources methods.

Examples

using SecretLabNAudio.Core.FileReading;

var assembly = typeof(MyPlugin).Assembly;

// attempts to load all readable resources
// MyPlugin.Audio.sus.wav -> MyPlugin.Audio.sus
// MyPlugin.Audio.mogus.ogg -> MyPlugin.Audio.mogus
ShortClipCache.AddAllFromEmbeddedResources(assembly);

// filter by file type (the period is trimmed)
// MyPlugin.Audio.sus.wav -> MyPlugin.Audio.sus
ShortClipCache.AddAllFromEmbeddedResources(assembly, "wav");

// specific resource names
// MyPlugin.Audio.mogus.ogg -> MyPlugin.Audio.sus.ogg
ShortClipCache.AddFromEmbeddedResource(assembly, "MyPlugin.Audio.mogus.ogg", trimExtension: false);

Tip

You can customize resource names by setting ManifestResourceName or LogicalName

Omit the namespace and folder structure

<ItemGroup>
    <!-- automatic mapping -->
    <EmbeddedResource Include="Audio/*" LogicalName="%(Filename)%(Extension)" /> 
    <!-- explicit definition -->
    <EmbeddedResource Include="Audio/sus.wav" LogicalName="sus.wav" />
</ItemGroup>

Manifest resource names before and after:

Before	After
MyPlugin.Audio.sus.wav	sus.wav
MyPlugin.Audio.mogus.ogg	mogus.ogg