media - Multimedia

Stability: 2 - Stable

The media module provides basic multimedia APIs. Currently it only supports music playback and media file scanning. Video playback and related features may be added later with UI integration.

Note: music playback is asynchronous in the background. When the script ends, playback stops automatically. You may need to keep the script alive (e.g. with sleep()). For example:

// Play music
media.playMusic("/sdcard/1.mp3");
// Wait until finished
sleep(media.getMusicDuration());

media.scanFile(path)

• path {string} Media file path

Scan the media file at path and add it to the media library; or if the file has been deleted, notify the media library to remove it.

The media library includes the photo gallery and music library, so you can use this to add an image file to the gallery.

media.playMusic(path[, volume, looping])

• path {string} Music file path
• volume {number} Playback volume (0~1 float), default 1
• looping {boolean} Loop playback. If true, loop; default false

Play the music file at path. This function does not show any music player UI. If the file does not exist or the format is not supported, it throws UncheckedIOException.

// Play music
media.playMusic("/sdcard/1.mp3");
// Wait until finished
sleep(media.getMusicDuration());

To loop the music, use the looping argument:

// Pass true as the third argument to loop
media.playMusic("/sdcard/1.mp3", 1, true);
// Wait for 3 loops
sleep(media.getMusicDuration() * 3);

If you want to use the system music player UI, call app.viewFile(path).

media.musicSeekTo(msec)

• msec {number} Milliseconds, playback position

Seek the current playback to msec. If no music is playing, this has no effect.

For example, seek to 1 minute: media.musicSeekTo(60 * 1000).

// Play music
media.playMusic("/sdcard/1.mp3");
// Seek to 30 seconds
media.musicSeekTo(30 * 1000);
// Wait until finished
sleep(media.getMusicDuration() - 30 * 1000);

media.pauseMusic()

Pause music playback. If no music is playing, this has no effect.

media.resumeMusic()

Resume music playback. If music has never been played, this has no effect.

media.stopMusic()

Stop music playback. If no music is playing, this has no effect.

media.isMusicPlaying()

• Returns {boolean}

Returns whether music is currently playing.

media.getMusicDuration()

• Returns {number}

Returns the duration of the current music in milliseconds.

media.getMusicCurrentPosition()

• Returns {number}

Returns the current playback position (elapsed time) in milliseconds.