Skip to main content

ExternalMusicModule

Class

Provides an interface to the ExternalMusic feature, and opts the Lens into using the feature when present in the scene.

  • Available on all platforms
Platform details: Snapchat, SPECS, Camera Kit Web, Camera Kit Mobile fully supported.

Platform details

  • Snapchat — Fully supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

Since Lens Scripting v297

Index

Remarks

When this module is present in a scene, an unbundled and licensed AudioTrack asset must be present in the scene as well. This means the Lens developer should:

  1. Import a licensed music track from the Asset Library
  2. On the imported audio asset, make sure Bundled is disabled
  3. Reference the audio asset somewhere in the scene (for example, @input audioAsset: AudioTrackAsset)

When this module is present in a Lens, the client running the Lens (either Snapchat or Lens Studio) will automatically fetch and auto-play the licensed music track included in the Lens.

This provides the benefits of:

  • The music file is not included in the lens, leading to smaller lens size
  • Special features like Lyrics may be available to the Lens, depending on the audio track
  • On Snapchat, a user can use the built-in music tool to adjust the music the Lens is using, and the Lens can react to that change

This also adds the following limitations, some of which are due to the inclusion of Licensed Audio Tracks:

  • The Lens cannot control or affect music playback, since it's controlled externally by the user.
  • The Lens must contain a single, unbundled Licensed Audio track. The Lens is not able to play it or any other audio through local methods, such as AudioComponent.
  • If device location is not available, or the track is not available in the user’s country, the sound in the Lens will be muted. The user will have an ability to remove or replace unavailable tracks.
  • The final audio will be mixed directly into the Lens.

Example

const externalMusicModule = require("LensStudio:ExternalMusicModule") as ExternalMusicModule;

@component
export class ExternalMusicExample extends BaseScriptComponent {
// Make sure an AudioTrack asset is included in the scene. It determines the track that plays.
// If you see errors, make sure that "Bundled" is unchecked (disabled) on the AudioTrack.
@input audioAsset: AudioTrackAsset;

onAwake() {
// Get LyricsTracker
const lyricsTracker = externalMusicModule.getLyricsTracker();

externalMusicModule.onTrackStarted.add(() => {
print("External music has started to play");
});

externalMusicModule.onTrackStopped.add(() => {
print("External music has stopped playback");
});

externalMusicModule.onTrackRemoved.add(() => {
print("External music track has been removed");
});

externalMusicModule.onTrackChanged.add(() => {
print("External music track has been changed");
});
}
}

Extends

Properties

isTrackSet

readonly isTrackSet: boolean

Returns true if an external music track is set.

Since

Lens Scripting Version 297


name

name: string

The name of the Asset in Lens Studio.

Default Value

""

Inherited from

Asset.name


onTrackChanged

readonly onTrackChanged: event1<ExternalMusicInfo, void>

Event that triggers when the external music track changes.

Since

Lens Scripting Version 297


onTrackRemoved

readonly onTrackRemoved: event0<void>

Event that fires when an external music track is removed.

Since

Lens Scripting Version 297


onTrackStarted

readonly onTrackStarted: event1<ExternalMusicInfo, void>

Event that fires when an external music track starts playing.

Since

Lens Scripting Version 297


onTrackStopped

readonly onTrackStopped: event0<void>

Event that fires when an external music track stops playing.

Since

Lens Scripting Version 297


uniqueIdentifier

readonly uniqueIdentifier: string

Since

Lens Scripting Version 176

Inherited from

Asset.uniqueIdentifier

Methods

getExternalMusicInfo()

getExternalMusicInfo(): ExternalMusicInfo

Returns the ExternalMusicInfo object for the current external music track. This can be used to compare two audio tracks during the Lens runtime.

Returns

ExternalMusicInfo

Since

Lens Scripting Version 297


getLyricsTracker()

getLyricsTracker(): LyricsTracker

Returns the LyricsTracker for the current external music track.

Returns

LyricsTracker

Since

Lens Scripting Version 297


getSoundSyncTracker()

getSoundSyncTracker(): SoundSyncTracker

Returns the sound sync (beats) tracker for the external music track.

Returns

SoundSyncTracker

Since

Lens Scripting Version 321


getTypeName()

static getTypeName(): TypeName<ExternalMusicModule>

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<ExternalMusicModule>

Since

Lens Scripting Version 297

Overrides

Asset.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

Asset.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

Asset.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

Asset.isSame