systemTonePlayer (System Tone Player) (System API)

The systemTonePlayer module provides APIs for playing and configuring SMS tones and notification tones and obtaining related information.

This module must work with @ohos.multimedia.systemSoundManager to manage system tones.

NOTE

The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs provided by this module are system APIs.

Modules to Import

import { systemSoundManager } from '@kit.AudioKit';

SystemToneOptions

Describes the options of system tones.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Name	Type	Mandatory	Description
muteAudio	boolean	No	Whether the sound is muted. The value true means that the sound is muted, and false means the opposite.
muteHaptics	boolean	No	Whether haptics feedback is turned off. The value true means that haptics feedback is turned off, and false means the opposite.

SystemTonePlayer

Implements APIs for playing and configuring SMS tones and notification tones and obtaining related information. Before calling any API in SystemTonePlayer, you must use getSystemTonePlayer to create a SystemTonePlayer instance.

getTitle

getTitle(): Promise<string>

Obtains the title of a system tone. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
Promise<string>	Promise used to return the title obtained.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
5400103	I/O error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

systemTonePlayer.getTitle().then((value: string) => {
  console.info(`Promise returned to indicate that the value of the system tone player title is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system tone player title ${err}`);
});

prepare

prepare(): Promise<void>

Prepares to play a system tone. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
5400102	Operation not allowed.
5400103	I/O error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

systemTonePlayer.prepare().then(() => {
  console.info(`Promise returned to indicate a successful prepareing of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to prepareing system tone player. ${err}`);
});

start

start(toneOptions?: SystemToneOptions): Promise<number>

Starts playing a system tone. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Required permissions: ohos.permission.VIBRATE

Parameters

Name	Type	Mandatory	Description
toneOptions	SystemToneOptions	No	Options of the system tone.

Return value

Type	Description
Promise<number>	Promise used to return the stream ID.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
201	Permission denied.
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102	Operation not allowed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

class SystemToneOptions {
  muteAudio: boolean = false;
  muteHaptics: boolean = false;
}
let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false};

systemTonePlayer.start(systemToneOptions).then((value: number) => {
  console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to start system tone player. ${err}`);
});

stop

stop(id: number): Promise<void>

Stops playing a system tone. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
id	number	Yes	Stream ID.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102	Operation not allowed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let streamID: number = 0; // streamID is the stream ID returned by start(). Only initialization is performed here.
systemTonePlayer.stop(streamID).then(() => {
  console.info(`Promise returned to indicate a successful stopping of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to stop system tone player. ${err}`);
});

release

release(): Promise<void>

Releases the system tone player. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Caller is not a system application.

Example

import { BusinessError } from '@kit.BasicServicesKit';

systemTonePlayer.release().then(() => {
  console.info(`Promise returned to indicate a successful releasing of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to release system tone player. ${err}`);
});

setAudioVolumeScale¹³⁺

setAudioVolumeScale(scale: number): void

Sets the scale of the audio volume. No result is returned.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
scale	number	Yes	Scale of the audio volume. The value is in the range [0, 1].

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102	Operation not allowed.
20700002	Parameter check error, For example, value is out side [0, 1].

Example

let scale: number = 0.5;
try {
  systemTonePlayer.setAudioVolumeScale(scale);
} catch (err) {
  console.error(`Failed to set audio volume scale. ${err}`);
}

getAudioVolumeScale¹³⁺

getAudioVolumeScale(): number

Obtains the scale of the audio volume. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
number	Scale of the audio volume.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Caller is not a system application.

Example

try {
  let scale: number = systemTonePlayer.getAudioVolumeScale();
  console.info(` get audio volume scale. ${scale}`);
} catch (err) {
  console.error(`Failed to get audio volume scale. ${err}`);
}

getSupportedHapticsFeatures¹³⁺

getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>>

Obtains the supported haptics styles. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
Promise<Array<systemSoundManager.ToneHapticsFeature>>	Promise used to return an array of the supported haptics styles.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
20700003	Unsupported operation.

Example

try {
  let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures();
  console.info(` get supported haptics features. ${features}`);
} catch (err) {
  console.error(`Failed to get supported haptics features. ${err}`);
}

setHapticsFeature¹³⁺

setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void

Sets a haptics style of the ringtone.

Before calling this API, call getSupportedHapticsFeatures to obtain the supported haptics styles. The setting fails if the haptics style to set is not supported.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
hapticsFeature	systemSoundManager.ToneHapticsFeature	Yes	Haptics style.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102	Operation not allowed.
20700003	Unsupported operation.

Example

try {
  let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures();
  if (features.lenght == 0) {
    return;
  }
  let feature: systemSoundManager.ToneHapticsFeature = features[0];
  systemTonePlayer.setHapticsFeature(feature);
  console.info(` set haptics feature success`);
} catch (err) {
  console.error(`Failed to set haptics feature. ${err}`);
}

getHapticsFeature¹³⁺

getHapticsFeature(): systemSoundManager.ToneHapticsFeature

Obtains the haptics style of the ringtone. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.SystemSound.Core

Return value

Type	Description
systemSoundManager.ToneHapticsFeature	Haptics style.

Error codes

For details about the error codes, see Universal Error Codes and Media Error Codes.

ID	Error Message
202	Caller is not a system application.
20700003	Unsupported operation.

Example

try {
  let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature();
  console.info(` get haptics feature success. ${features}`);
} catch (err) {
  console.error(`Failed to get haptics feature. ${err}`);
}

on('playFinished')¹⁸⁺

on(type: 'playFinished', streamId: number, callback: Callback<number>): void

Subscribes to the event indicating that the ringtone playback is finished. This API uses an asynchronous callback to return the result.

The object to listen for is an audio stream specified by streamId. If streamId is set to 0, this API subscribes to the playback complete event of all audio streams of the player.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'playFinished' is triggered when the playback is finished.
streamId	number	Yes	ID of the audio stream. streamId is obtained through start. If streamId is set to 0, the playback complete event of all audio streams of the player is subscribed to.
callback	Callback<number>	Yes	Callback used to return the stream ID of the audio stream that finishes playing.

Error codes

For details about the error codes, see Universal Error Codes and Ring Error Codes.

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Subscribe to the playback complete events of all audio streams.
systemTonePlayer.on('playFinished', 0, (streamId: number) => {
  console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
});

// Subscribe to the playback complete event of a specified audio stream.
systemTonePlayer.start().then((value: number) => {
  systemTonePlayer.on('playFinished', value, (streamId: number) => {
    console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to start system tone player. ${err}`);
});

off('playFinished')¹⁸⁺

off(type: 'playFinished', callback?: Callback<number>): void

Unsubscribes from the event indicating that the ringtone playback is finished. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'playFinished' is triggered when the playback is finished.
callback	Callback<number>	No	Callback used to return the ID of the audio stream. If this parameter is not specified, all the subscriptions to the specified event are canceled.

Error codes

For details about the error codes, see Universal Error Codes and Ring Error Codes.

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

Example

// Cancel all subscriptions to the event.
systemTonePlayer.off('playFinished');

// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter.
let playFinishedCallback = (streamId: number) => {
  console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
};

systemTonePlayer.on('playFinished', 0, playFinishedCallback);

systemTonePlayer.off('playFinished', playFinishedCallback);

on('error')¹⁸⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events that occur during ringtone playback. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'error' is triggered when an error occurs during ringtone playback.
callback	ErrorCallback	Yes	Callback used to return the error code and error information. For details about the error codes, see on('error') of the AVPlayer.

Error codes

For details about the error codes, see Universal Error Codes and Ring Error Codes.

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

systemTonePlayer.on('error', (err: BusinessError) => {
  console.log("on error, err:" + JSON.stringify(err));
});

off('error')¹⁸⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events that occur during ringtone playback. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.SystemSound.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'error' is triggered when an error occurs during ringtone playback.
callback	ErrorCallback	No	Callback used to return the error code and error information. If this parameter is not specified, all the subscriptions to the specified event are canceled.

Error codes

For details about the error codes, see Universal Error Codes and Ring Error Codes.

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Cancel all subscriptions to the event.
systemTonePlayer.off('error');

// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter.
let callback = (err: BusinessError) => {
  console.log("on error, err:" + JSON.stringify(err));
};

systemTonePlayer.on('error', callback);

systemTonePlayer.off('error', callback);

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Audio Kit

harmony 鸿蒙OH_AudioCapturer_Callbacks_Struct

harmony 鸿蒙OH_AudioDeviceDescriptorArray

harmony 鸿蒙OH_AudioRenderer_Callbacks_Struct

harmony 鸿蒙OH_AudioSession_DeactivatedEvent

harmony 鸿蒙OH_AudioSession_Strategy

harmony 鸿蒙_o_h_audio

harmony 鸿蒙Audio Error Codes

harmony 鸿蒙Ringtone Error Codes

harmony 鸿蒙js-apis-audio-sys

openharmony 鸿蒙 js-apis-inner-multimedia-systemTonePlayer-sys

systemTonePlayer (System Tone Player) (System API)

Modules to Import

SystemToneOptions

SystemTonePlayer

getTitle

prepare

start

stop

release

setAudioVolumeScale¹³⁺

getAudioVolumeScale¹³⁺

getSupportedHapticsFeatures¹³⁺

setHapticsFeature¹³⁺

getHapticsFeature¹³⁺

on('playFinished')¹⁸⁺

off('playFinished')¹⁸⁺

on('error')¹⁸⁺

off('error')¹⁸⁺

你可能感兴趣的鸿蒙文章

最新博客

最热博客

标签云

systemTonePlayer (System Tone Player) (System API)

Modules to Import

SystemToneOptions

SystemTonePlayer

getTitle

prepare

start

stop

release

setAudioVolumeScale13+

getAudioVolumeScale13+

getSupportedHapticsFeatures13+

setHapticsFeature13+

getHapticsFeature13+

on('playFinished')18+

off('playFinished')18+

on('error')18+

off('error')18+

你可能感兴趣的鸿蒙文章

最新博客

最热博客

setAudioVolumeScale¹³⁺

getAudioVolumeScale¹³⁺

getSupportedHapticsFeatures¹³⁺

setHapticsFeature¹³⁺

getHapticsFeature¹³⁺

on('playFinished')¹⁸⁺

off('playFinished')¹⁸⁺

on('error')¹⁸⁺

off('error')¹⁸⁺