1/*
2 * Copyright (c) 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 { Callback, AsyncCallback } from '../@ohos.base';
22import type audio from '../@ohos.multimedia.audio';
23import type media from '../@ohos.multimedia.media';
24
25/**
26 * Interface for ringtone options.
27 * @typedef RingtoneOptions
28 * @syscap SystemCapability.Multimedia.SystemSound.Core
29 * @systemapi
30 * @since 10
31 */
32export interface RingtoneOptions {
33  /**
34   * Ringtone volume.
35   * @type { number }
36   * @syscap SystemCapability.Multimedia.SystemSound.Core
37   * @systemapi
38   * @since 10
39   */
40  volume: number;
41  /**
42   * Loop value.
43   * @type { boolean }
44   * @syscap SystemCapability.Multimedia.SystemSound.Core
45   * @systemapi
46   * @since 10
47   */
48  loop: boolean;
49}
50
51/**
52 * Ringtone player object.
53 * @typedef RingtonePlayer
54 * @syscap SystemCapability.Multimedia.SystemSound.Core
55 * @systemapi
56 * @since 10
57 */
58export interface RingtonePlayer {
59  /**
60   * Gets player state.
61   * @type { media.AVPlayerState }
62   * @syscap SystemCapability.Multimedia.SystemSound.Core
63   * @systemapi
64   * @since 10
65   */
66  readonly state: media.AVPlayerState;
67
68  /**
69   * Gets the title of ringtone.
70   * @param { AsyncCallback<string> } callback - Callback used to return the title.
71   * @syscap SystemCapability.Multimedia.SystemSound.Core
72   * @systemapi
73   * @since 10
74   */
75  getTitle(callback: AsyncCallback<string>): void;
76  /**
77   * Gets the title of ringtone.
78   * @returns { Promise<string> } Promise used to return the title.
79   * @syscap SystemCapability.Multimedia.SystemSound.Core
80   * @systemapi
81   * @since 10
82   */
83  getTitle(): Promise<string>;
84
85  /**
86   * Gets audio renderer info.
87   * @param { AsyncCallback<audio.AudioRendererInfo> } callback - Callback used to return AudioRendererInfo value.
88   * @syscap SystemCapability.Multimedia.SystemSound.Core
89   * @systemapi
90   * @since 10
91   */
92  getAudioRendererInfo(callback: AsyncCallback<audio.AudioRendererInfo>): void;
93  /**
94   * Gets audio renderer info.
95   * @returns { Promise<audio.AudioRendererInfo> } Promise used to return AudioRendererInfo value.
96   * @syscap SystemCapability.Multimedia.SystemSound.Core
97   * @systemapi
98   * @since 10
99   */
100  getAudioRendererInfo(): Promise<audio.AudioRendererInfo>;
101
102  /**
103   * Configure ringtone options.
104   * @param { RingtoneOptions } options - Ringtone configure options.
105   * @param { AsyncCallback<void> } callback - Callback used to return configuration result.
106   * @syscap SystemCapability.Multimedia.SystemSound.Core
107   * @systemapi
108   * @since 10
109   */
110  configure(options: RingtoneOptions, callback: AsyncCallback<void>): void;
111  /**
112   * Configure ringtone options.
113   * @param { RingtoneOptions } options - Ringtone configure options.
114   * @returns { Promise<void> } Promise used to return configuration result.
115   * @syscap SystemCapability.Multimedia.SystemSound.Core
116   * @systemapi
117   * @since 10
118   */
119  configure(options: RingtoneOptions): Promise<void>;
120
121  /**
122   * Starts playing ringtone.
123   * @param { AsyncCallback<void> } callback - Callback used to return the starting result.
124   * @syscap SystemCapability.Multimedia.SystemSound.Core
125   * @systemapi
126   * @since 10
127   */
128  start(callback: AsyncCallback<void>): void;
129  /**
130   * Starts playing ringtone.
131   * @returns { Promise<void> } Promise used to return the starting result.
132   * @syscap SystemCapability.Multimedia.SystemSound.Core
133   * @systemapi
134   * @since 10
135   */
136  start(): Promise<void>;
137
138  /**
139   * Stop playing ringtone.
140   * @param { AsyncCallback<void> } callback - Callback used to return the stopping result.
141   * @syscap SystemCapability.Multimedia.SystemSound.Core
142   * @systemapi
143   * @since 10
144   */
145  stop(callback: AsyncCallback<void>): void;
146  /**
147   * Stop playing ringtone.
148   * @returns { Promise<void> } Promise used to return the stopping result.
149   * @syscap SystemCapability.Multimedia.SystemSound.Core
150   * @systemapi
151   * @since 10
152   */
153  stop(): Promise<void>;
154
155  /**
156   * Release ringtone player resource.
157   * @param { AsyncCallback<void> } callback - Callback used to return the releasing result.
158   * @syscap SystemCapability.Multimedia.SystemSound.Core
159   * @systemapi
160   * @since 10
161   */
162  release(callback: AsyncCallback<void>): void;
163  /**
164   * Release ringtone player resource.
165   * @returns { Promise<void> } Promise used to return the releasing result.
166   * @syscap SystemCapability.Multimedia.SystemSound.Core
167   * @systemapi
168   * @since 10
169   */
170  release(): Promise<void>;
171
172  /**
173   * Listens for audio interrupt events. This method uses a callback to get interrupt events. The interrupt event is
174   * triggered when audio playback is interrupted.
175   * @param { 'audioInterrupt' } type - Type of the event to listen for. Only the audioInterrupt event is supported.
176   * @param { Callback<audio.InterruptEvent> } callback - Callback used to listen for interrupt callback.
177   * @throws { BusinessError } 401 - Parameter error. Possible causes:
178   *                                 1.Mandatory parameters are left unspecified;
179   *                                 2.Incorrect parameter types.
180   * @throws { BusinessError } 6800101 - Parameter verification failed.
181   * @syscap SystemCapability.Multimedia.SystemSound.Core
182   * @systemapi
183   * @since 10
184   */
185  on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void;
186
187  /**
188   * Unsubscribes to audio interrupt events.
189   * @param { 'audioInterrupt' } type - Type of the event to listen for. Only the audioInterrupt event is supported.
190   * @throws { BusinessError } 401 - Parameter error. Possible causes:
191   *                                 1.Mandatory parameters are left unspecified;
192   *                                 2.Incorrect parameter types.
193   * @throws { BusinessError } 6800101 - Parameter verification failed.
194   * @syscap SystemCapability.Multimedia.SystemSound.Core
195   * @systemapi
196   * @since 10
197   */
198  off(type: 'audioInterrupt'): void
199}