1/* 2 * Copyright (c) 2023-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit AudioKit 19 */ 20 21import type systemSoundManager from '../@ohos.multimedia.systemSoundManager'; 22import { ErrorCallback, Callback } from '../@ohos.base'; 23/** 24 * System tone player object. 25 * @typedef SystemTonePlayer 26 * @syscap SystemCapability.Multimedia.SystemSound.Core 27 * @systemapi 28 * @since 11 29 */ 30export interface SystemTonePlayer { 31 /** 32 * Gets the title of system tone. 33 * @returns { Promise<string> } Promise used to return the title. 34 * @throws { BusinessError } 202 - Caller is not a system application. 35 * @throws { BusinessError } 5400103 - I/O error. 36 * @syscap SystemCapability.Multimedia.SystemSound.Core 37 * @systemapi 38 * @since 11 39 */ 40 getTitle(): Promise<string>; 41 42 /** 43 * Sets the volume scale of audio. 44 * @param { number } scale - Audio volume scale, should be float in [0,1] 45 * @throws { BusinessError } 202 - Caller is not a system application. 46 * @throws { BusinessError } 401 - Parameter error. Possible causes: 47 * 1.Mandatory parameters are left unspecified; 48 * 2.Incorrect parameter types. 49 * @throws { BusinessError } 5400102 - Operation not allowed. 50 * @throws { BusinessError } 20700002 - Parameter check error. For example, value is outside [0,1]. 51 * @syscap SystemCapability.Multimedia.SystemSound.Core 52 * @systemapi 53 * @since 13 54 */ 55 setAudioVolumeScale(scale: number): void; 56 57 /** 58 * Gets the volume scale of audio. 59 * @returns { number } Audio volume scale. 60 * @throws { BusinessError } 202 - Caller is not a system application. 61 * @syscap SystemCapability.Multimedia.SystemSound.Core 62 * @systemapi 63 * @since 13 64 */ 65 getAudioVolumeScale(): number; 66 67 /** 68 * Get supported haptics features currently. 69 * @returns { Promise<Array<systemSoundManager.ToneHapticsFeature>> } Promise used to return result of this call. 70 * @throws { BusinessError } 202 - Caller is not a system application. 71 * @throws { BusinessError } 20700003 - Unsupported operation. 72 * @syscap SystemCapability.Multimedia.SystemSound.Core 73 * @systemapi 74 * @since 13 75 */ 76 getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>>; 77 78 /** 79 * Set haptic feature that is used when playing. 80 * @param { systemSoundManager.ToneHapticsFeature } hapticsFeature - haptics Feature. 81 * @throws { BusinessError } 202 - Caller is not a system application. 82 * @throws { BusinessError } 401 - Parameter error. Possible causes: 83 * 1.Mandatory parameters are left unspecified; 84 * 2.Incorrect parameter types. 85 * @throws { BusinessError } 5400102 - Operation not allowed. 86 * @throws { BusinessError } 20700003 - Unsupported operation. 87 * @syscap SystemCapability.Multimedia.SystemSound.Core 88 * @systemapi 89 * @since 13 90 */ 91 setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void; 92 93 /** 94 * Get haptic feature that is used when playing. 95 * @returns { systemSoundManager.ToneHapticsFeature } haptics feature that is used when playing. 96 * @throws { BusinessError } 202 - Caller is not a system application. 97 * @throws { BusinessError } 20700003 - Unsupported operation. 98 * @syscap SystemCapability.Multimedia.SystemSound.Core 99 * @systemapi 100 * @since 13 101 */ 102 getHapticsFeature(): systemSoundManager.ToneHapticsFeature; 103 104 /** 105 * Prepare to play. 106 * @returns { Promise<void> } Promise used to return result of prepare. 107 * @throws { BusinessError } 202 - Caller is not a system application. 108 * @throws { BusinessError } 5400102 - Operation not allowed. 109 * @throws { BusinessError } 5400103 - I/O error. 110 * @syscap SystemCapability.Multimedia.SystemSound.Core 111 * @systemapi 112 * @since 11 113 */ 114 prepare(): Promise<void>; 115 116 /** 117 * Start playing the system tone. By default, the audio and haptic will not be muted. Using tone options to mute audio 118 * or haptics. If haptics is needed, caller should have the permission of ohos.permission.VIBRATE. 119 * @permission ohos.permission.VIBRATE 120 * @param { SystemToneOptions } toneOptions - Tone options used for this play. 121 * @returns { Promise<number> } Promise used to return the id of this playback. 122 * @throws { BusinessError } 201 - Permission denied. 123 * @throws { BusinessError } 202 - Caller is not a system application. 124 * @throws { BusinessError } 401 - Parameter error. Possible causes: 125 * 1.Mandatory parameters are left unspecified; 126 * 2.Incorrect parameter types. 127 * @throws { BusinessError } 5400102 - Operation not allowed. 128 * @syscap SystemCapability.Multimedia.SystemSound.Core 129 * @systemapi 130 * @since 11 131 */ 132 start(toneOptions?: SystemToneOptions): Promise<number>; 133 134 /** 135 * Stop with playback id. 136 * @param { number } id - The Playback id to stop. 137 * @returns { Promise<void> } Promise used to return result of this stop. 138 * @throws { BusinessError } 202 - Caller is not a system application. 139 * @throws { BusinessError } 401 - Parameter error. Possible causes: 140 * 1.Mandatory parameters are left unspecified; 141 * 2.Incorrect parameter types. 142 * @throws { BusinessError } 5400102 - Operation not allowed. 143 * @syscap SystemCapability.Multimedia.SystemSound.Core 144 * @systemapi 145 * @since 11 146 */ 147 stop(id: number): Promise<void>; 148 149 /** 150 * Release this system tone player. 151 * @returns { Promise<void> } Promise used to return result of release. 152 * @throws { BusinessError } 202 - Caller is not a system application. 153 * @syscap SystemCapability.Multimedia.SystemSound.Core 154 * @systemapi 155 * @since 11 156 */ 157 release(): Promise<void>; 158 159 /** 160 * Subscribes the play finished events. 161 * @param { 'playFinished' } type - Type of the event to listen for. 162 * @param { number } streamId - Stream id, received from start(). 163 * @param { Callback<number> } callback - Callback used to obtain the finished event. The callback info is the stream 164 * id that is finished. 165 * @throws { BusinessError } 202 - Not system App. 166 * @throws { BusinessError } 20700002 -Parameter check error. 167 * @syscap SystemCapability.Multimedia.SystemSound.Core 168 * @systemapi 169 * @since 18 170 */ 171 on(type: 'playFinished', streamId: number, callback: Callback<number>): void; 172 173 /** 174 * Unsubscribes the play finished events. 175 * @param { 'playFinished' } type - Type of the event to listen for. 176 * @param { Callback<number> } callback - Callback used to obtain the finished event. 177 * @throws { BusinessError } 202 - Not system App. 178 * @throws { BusinessError } 20700002 -Parameter check error. 179 * @syscap SystemCapability.Multimedia.SystemSound.Core 180 * @systemapi 181 * @since 18 182 */ 183 off(type: 'playFinished', callback?: Callback<number>): void; 184 185 /** 186 * Subscribes the error events. 187 * @param { 'error'} type - Type of the event to listen for. 188 * @param { ErrorCallback } callback - Error callback while receiving the error event. 189 * @throws { BusinessError } 202 - Not system App. 190 * @throws { BusinessError } 20700002 -Parameter check error. 191 * @syscap SystemCapability.Multimedia.SystemSound.Core 192 * @systemapi 193 * @since 18 194 */ 195 on(type: 'error', callback: ErrorCallback): void; 196 197 /** 198 * Unsubscribes the error events. 199 * @param { 'error'} type - Type of the event to listen for. 200 * @param { ErrorCallback } callback - Error callback while receiving the error event. 201 * @throws { BusinessError } 202 - Not system App. 202 * @throws { BusinessError } 20700002 -Parameter check error. 203 * @syscap SystemCapability.Multimedia.SystemSound.Core 204 * @systemapi 205 * @since 18 206 */ 207 off(type: 'error', callback?: ErrorCallback): void 208} 209 210/** 211 * System tone options used when SystemTonePlayer start playing. 212 * @typedef SystemToneOptions 213 * @syscap SystemCapability.Multimedia.SystemSound.Core 214 * @systemapi 215 * @since 11 216 */ 217export interface SystemToneOptions { 218 /** 219 * Mute audio. 220 * @type {?boolean} 221 * @syscap SystemCapability.Multimedia.SystemSound.Core 222 * @systemapi 223 * @since 11 224 */ 225 muteAudio?: boolean; 226 227 /** 228 * Mute haptics. 229 * @type {?boolean} 230 * @syscap SystemCapability.Multimedia.SystemSound.Core 231 * @systemapi 232 * @since 11 233 */ 234 muteHaptics?: boolean; 235}