Multimedia

Importing Modules

import media from '@system.media'

API Definitions

method

Creates an AudioPlayer object.

method

Creates an AudioRecorder object.

Developers need to declare the application's access permission for watch.permission.RECORD in the manifest.json file.

method

Sets the system media volume. The volume parameter is a volume value between $[0.0, 1.0]$. This property is used for system media volume control, and the specific functionality depends on the platform implementation. To adjust the volume, the volume property of the AudioPlayer object should be prioritized.

method

Gets the system media volume. The result is a volume value between $[0.0, 1.0]$. This property is used for retrieving the system media volume, and the specific functionality depends on the platform implementation. To get the volume, the volume property of the AudioPlayer object should be prioritized.

AudioPlayer Object

Type Signature

interface AudioPlayer {
  src: string,
  name: string,
  icon: string,
  mode: string,
  status: string,
  duration: number,
  position: number,
  openSystemNotification: bool,
  songAttribute: object,
  volume: number,
  nextAvailable: bool,
  prevAvailable: bool,

  play(): void,
  pause(): void,
  stop(): void,
  release(): void,
  next(): void,
  previous(): void,
  requestFocus({acquireType: string, volumeType: string}): void,
  releaseFocus(): void,

  onplay?: () => void,
  onpause?: () => void,
  onstop?: () => void,
  onended?: () => void,
  onerror?: (err: {msg: string})=> void,
  ontimeupdate?: () => void,
  oninterrupt?: (action: {interruptHint: number}) => void,
  onnext?: () => void,
  onprevious?: () => void,
  onrequestplay?: () => void,
  onrequestpause?: () => void,
  onrequeststop?: () => void,
  onsongattribute?: () => void,
  onposition?: () => void,
  onrequestfocus?: () => void,
  onreleasefocus?: () => void,
  onmodechanged?: () => void,
  onvolumechange?: () => void,
}

get • set

Sets or reads the URL of the audio to be played. Supports local resource paths and network resource paths using http or https protocols (e.g., https://www.rt-thread.com/service/test/001.mp3). Below is a simple example of setting the src and then starting playback:

import media from '@system.media'
// Create audio player
let player = media.createAudioPlayer()
// Set the audio URL to be played
player.src = 'https://www.rt-thread.com/service/test/001.mp3'
// Start playing audio
player.play()

get • set

The name of the player object. If not set, it defaults to the name of the application that created the player. Note that the name of the player object is not globally unique, and the name cannot be used to identify the player object.

get • set

The icon URL of the player object. Supports local resource paths

get • set

Playback mode. The functionality corresponding to this property should be implemented by the player application; the player object does not handle it by default and only provides this property.

• sequential: Sequential playback
• random: Random playback
• singleloop: Single track loop
• listloop: List loop

get

Read the current player state

• play: Playing status
• pause: Paused status
• stop: Stopped status
• ended: Ended status
• error: Error status

get

Total audio duration, unit: seconds

get • set

Current audio playback time position, unit: seconds

get • set

Whether to enable system notifications; disabled by default. Once enabled, this
player object can be queried by the Audio Player Manager.

get • set

Song attribute object

Type Signature

type songAttribute = {
  title: string; // Song title
  artist: string; // Performer's name, can be an individual or a band
  album: string; // Name of the album the song belongs to
  year: string; // Release year of the song
  genre: string; // Genre of the song, e.g., pop, rock, classical, etc.
  track: string; // Track number in the album, e.g., "1/12" means 1st of 12
  coverArt: string; // URL of the song's cover art image
  lyrics: string; // URL of the lyrics text
  comments: string; // Additional information, such as copyright notes, etc.
}

The songAttribute object, like the AudioPlayer object, is a Proxy object, meaning it cannot be serialized or deserialized using JSON, nor can it be referenced in reactive frameworks. Below is a simple usage example:

// Set the song title
this.player.songAttribute.title = "Unknown"
// Set the song artist
this.player.songAttribute.artist = "Unknown"
// Check the song title
console.dir(this.player.songAttribute.title)

get • set

The current player volume, range: [0.0, 1.0]

get • set

Sets or queries whether switching to the next track is available

get • set

Sets or queries whether switching to the previous track is available

method

Starts playing the audio specified in the src property

• If the src property is not set before calling this method, playback will fail and trigger the onerror event;
• This method is a synchronous interface. After execution, you need to wait for the onplay or onerror event to determine success or failure. Other operations performed before the event is triggered will be ignored;

Below is a simple example of calling the play() interface:

import media from '@system.media'
// Create audio player
let player = media.createAudioPlayer()
// Set the audio URL to be played
player.src = 'https://www.rt-thread.com/service/test/001.mp3'
// Set onplay event
player.onplay = () => { console.dir("Start playing") }
// Set onerror event
player.onerror = () => { console.dir("Playback error") }
// Start playing audio
player.play()

method

Pauses playback of the current audio.

• This method is a synchronous interface. After executing this interface, you need to wait for the onpause event or onerror event to determine whether the pause succeeded or failed. Other operations performed before the event is triggered will be ignored.

method

Stops audio playback. Audio can be replayed via play.

• This method is a synchronous interface. After executing this interface, you need to wait for the onstop event or onerror event to determine whether the stop succeeded or failed. Other operations performed before the event is triggered will be ignored.

method

Releases audio resources.

• Executing this interface will stop playback of the current audio. You need to wait for the onstop event or onerror event to determine whether the stop succeeded or failed. Other operations performed before the event is triggered will be ignored.

method

Notifies the player application to play the next track. After executing this interface, the onnext event will be triggered to notify the player application listening to this event, and the player application will execute the song switching logic.

method

Notifies the player application to play the previous track. After executing this interface, the onprevious event will be triggered to notify the player application listening to this event, and the player application will execute the song switching logic.

method

Requests audio focus. After executing this interface, it notifies the underlying layer to request or release audio focus, and the underlying layer controls the switching and interruption logic for different types of audio.

The acquireType parameter indicates the request type:

• gain: Request audio focus
• loss: Release audio focus

The volumeType parameter indicates the audio type:

• system: System notification
• media: Media music
• tts: Text-to-speech (TTS) broadcast

The following example demonstrates how the requestFocus function requests audio focus:

import media from '@system.media'
// Create audio player
let player = media.createAudioPlayer()
// Request audio focus for media music type
player.requestFocus({ volumeType: 'media', acquireType: 'gain' });

method

Releases audio focus. After calling this interface, the underlying system is notified to release audio focus, and the underlying system controls the switching and interruption logic for different audio types.

set

Callback event after audio play succeeds

set

Callback event after audio pause succeeds

set

Callback event after audio stop succeeds

set

Callback event after audio playback ends

set

Callback event when an error occurs while executing interfaces such as play, pause, stop, or position. When an error occurs, the corresponding events like onplay will not be triggered.

set

Callback event triggered when the position property is updated. This event is only triggered when the application is in the foreground and stops being dispatched when the application is in the background.

set

Callback function for audio interruption events. Notification when the current audio is temporarily or completely interrupted by audio of the same or different types.

The interruptHint of the action parameter indicates the type of interruption event:

• 1: Brief interruption (can automatically resume, e.g., music being interrupted)
• 2: Permanent interruption (cannot automatically resume, e.g., NetEase Cloud Music being interrupted by Ximalaya)

The following example demonstrates how to register the oninterrupt callback function, which is called when the event occurs:

player.oninterrupt = (action) => {
  console.log(action.interruptHint)
}

set

Callback event when the next track needs to be played.

set

Callback event when the previous track needs to be played.

set

This callback event is triggered to notify the JS application when the underlying system needs to start playback. The JS application then executes the logic to start playback.

set

This callback event is triggered to notify the JS application when the underlying system needs to pause playback. The JS application then executes the logic to pause playback.

set

This callback event is triggered to notify the JS application when the underlying system needs to stop playback. The JS application then executes the logic to stop playback.

set

Callback event when the song attribute object changes.

set

Callback event when successfully setting the current audio playback time position using position.

set

Callback event when the request for audio focus is successful.

set

Callback event when audio focus is successfully released

set

Callback event when the playback mode changes

set

Callback event when the player volume changes

AudioRecorder Object

Type Signature

interface AudioRecorder {
    start({
      uri: string, 
      sample?: 8000 | 16000 | 44100 | 48000,
      layout?: 8 | 16 | 32,
      channel?: 1 | 2,
      bitrate?: 16 | 32 | 64,
      codec?: "pcm" | "mp3" | "opus" | "silk",
      format?: "ogg",
    }): Promise<void>,
    read({callback: (ArrayBuffer) => void}): void,
    stop(): void,
    release(): void,
    onstart?: () => void,
    onstop?: () => void,
    onrelease?: () => void,
    onavailable?: (ArrayBuffer) => void,
    onerror?: ({error: string})=> void
}

start

method

Start recording audio. The functions of each field in the options parameter are:

• uri: The URI of the recording file to be stored. Only the internal protocol is supported, and directories will be created automatically;
• sample: Audio sampling rate in $\rm Hz$, defaults to $8000$;
• layout: Audio data bit depth, defaults to $16$;
• channel: Number of audio channels, defaults to $1$;
• bitrate: Audio bitrate in $\rm kbps$, defaults to $16$. Higher bitrate means better sound quality but larger file size.
• codec: Audio encoding format, string type. If not specified, a suitable encoding will be automatically matched based on the format parameter;
• format: Audio container format, string type. If not specified, a suitable container will be automatically matched based on the suffix of the uri parameter;

The support relationships between common recording formats, encoding formats, and container formats are as follows ("None" in the table means the corresponding parameter can be left blank):

Common Recording Formats	codec (Encoding Format)	format (Container Format)
pcm	None	None
mp3	mp3	None
opus	opus	None
opus-ogg	opus	ogg
silk	silk	None

The following is the sample code to start recording:

let recorder = media.createAudioRecord()
recorder.start({
  uri: "internal://tmp/media_test.mp3",
  sample: 16000,
  layout: 16,
  channel: 1,
  bitrate: 16
})

Info

For more information about the internal URI protocol, please refer to the Resource Access documentation.

After recording is complete, please call the stop() method to end the recording.

read

method

Reads the recorded audio data (each read retrieves all available data from the end position of the previous read to the current moment).

method

Stops recording audio. After calling this interface, the audio file recorded by the start() method (specified by the uri parameter) can be read by other modules.

method

Releases audio recording resources.

set

Callback event after recording starts.

set

Callback event after recording stops.

set

Callback event after recording is released.

set

Callback event when new data is generated after recording starts.

set

Callback event for errors occurring during start, stop, or release events. When an error occurs, the corresponding onstart etc. will not be triggered.

Examples

Audio Recording

The following code demonstrates the simplest example of recording 3 seconds of audio:

import media from "@system.media"

async function record() {
  // Create an audio recording object
  let record = media.createAudioRecord()
  console.log('start record')
  // Only the uri parameter is provided; other parameters use default values
  await record.start({
    uri: 'internal://tmp/test.mp3'
  })
  setTimeout(() => {
    console.log('stop record')
    record.stop() // Stop recording after a 3-second delay
  }, 3000)
}

record()

Calling the record() function creates an audio recording object, starts recording, and stops after 3 seconds. The recording is saved to the internal://tmp/test.mp3 file and encoded in MP3 format.

This example only passes the uri parameter to the AudioPlayer.start() method; sample, layout, channel, and bitrate all use default configurations.

Tips

When using the emulator, you can find and play the recording file in the application's data directory. The file path corresponding to internal://tmp/test.mp3 is .glyphix-work/image/{device}/data/temp/{app-id}/test.mp3, where {device} and {app-id} are the device name and application name during emulation.