ExternalMusicModule
ClassProvides an interface to the ExternalMusic feature, and opts the Lens into using the feature when present in the scene.
- Available on all platforms
Since Lens Scripting v297
Index
Properties
Methods
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:
- Import a licensed music track from the Asset Library
- On the imported audio asset, make sure
Bundledis disabled - 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
readonlyisTrackSet: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
onTrackChanged
readonlyonTrackChanged:event1<ExternalMusicInfo,void>
Event that triggers when the external music track changes.
Since
Lens Scripting Version 297
onTrackRemoved
readonlyonTrackRemoved:event0<void>
Event that fires when an external music track is removed.
Since
Lens Scripting Version 297
onTrackStarted
readonlyonTrackStarted:event1<ExternalMusicInfo,void>
Event that fires when an external music track starts playing.
Since
Lens Scripting Version 297
onTrackStopped
readonlyonTrackStopped:event0<void>
Event that fires when an external music track stops playing.
Since
Lens Scripting Version 297
uniqueIdentifier
readonlyuniqueIdentifier:string
Since
Lens Scripting Version 176
Inherited from
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
Since
Lens Scripting Version 297
getLyricsTracker()
getLyricsTracker():
LyricsTracker
Returns the LyricsTracker for the current external music track.
Returns
Since
Lens Scripting Version 297
getSoundSyncTracker()
getSoundSyncTracker():
SoundSyncTracker
Returns the sound sync (beats) tracker for the external music track.
Returns
Since
Lens Scripting Version 321
getTypeName()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean