import { AsyncVoidIOResult, AsyncIOResult } from 'happy-rusty';

/**
 * 播放音频的选项。
 * @since 1.5.0
 * @example
 * ```ts
 * import { audio } from 'minigame-std';
 *
 * // 循环播放
 * const source = audio.playWebAudioFromAudioBuffer(buffer, { loop: true });
 *
 * // 禁用自动断开连接
 * const source2 = audio.playWebAudioFromAudioBuffer(buffer, { autoDisconnect: false });
 * ```
 */
interface PlayOptions {
    /**
     * 是否循环播放。
     * @defaultValue `false`
     */
    loop?: boolean;
    /**
     * 播放完后是否自动调用 `source.disconnect`。
     * @defaultValue `true`
     */
    autoDisconnect?: boolean;
}

/**
 * Web/小游戏 平台的音频播放实现。
 */

/**
 * 获取缓存的 AudioContext。
 * @returns 返回缓存的 AudioContext。
 * @since 1.5.0
 * @example
 * ```ts
 * const context = audio.getGlobalAudioContext();
 * ```
 */
declare function getGlobalAudioContext(): AudioContext;
/**
 * 关闭缓存的 AudioContext。
 * @returns 返回一个 AsyncVoidIOResult。
 * @since 1.5.0
 * @example
 * ```ts
 * await audio.closeGlobalAudioContext();
 * ```
 */
declare function closeGlobalAudioContext(): AsyncVoidIOResult;
/**
 * 创建一个 AudioContext。
 * 如果要获取缓存的实例，请使用 `getGlobalAudioContext`。
 * @returns 返回一个 AudioContext实例。
 * @since 1.5.0
 * @example
 * ```ts
 * const context = audio.createWebAudioContext();
 * ```
 */
declare function createWebAudioContext(): AudioContext;
/**
 * 播放一个 AudioBuffer。
 * @param buffer - 解码后的 AudioBuffer。
 * @param options - 播放选项。
 * @returns 正在播放的 AudioBufferSourceNode。
 * @since 1.5.0
 * @example
 * ```ts
 * const source = audio.playWebAudioFromAudioBuffer(audioBuffer, { loop: true });
 * ```
 */
declare function playWebAudioFromAudioBuffer(buffer: AudioBuffer, options?: PlayOptions): AudioBufferSourceNode;
/**
 * 使用 Buffer 进行解码播放。
 * @param buffer - 需要解码的 Buffer。
 * @param options - 播放选项。
 * @returns 正在播放的 AudioBufferSourceNode。
 * @since 1.5.0
 * @example
 * ```ts
 * const result = await audio.playWebAudioFromBufferSource(buffer);
 * if (result.isOk()) {
 *     const source = result.unwrap();
 * }
 * ```
 */
declare function playWebAudioFromBufferSource(buffer: BufferSource, options?: PlayOptions): AsyncIOResult<AudioBufferSourceNode>;
/**
 * 读取文件并播放。
 * @param filePath - 文件路径。
 * @param options - 播放选项。
 * @returns 正在播放的 AudioBufferSourceNode。
 * @since 1.5.0
 * @example
 * ```ts
 * const result = await audio.playWebAudioFromFile('/path/to/audio.mp3');
 * if (result.isOk()) {
 *     const source = result.unwrap();
 * }
 * ```
 */
declare function playWebAudioFromFile(filePath: string, options?: PlayOptions): AsyncIOResult<AudioBufferSourceNode>;
/**
 * 从远程 URL 下载音频并解码播放。
 * 会先完整下载音频数据再调用 `decodeAudioData`，适合短音效，不适合长音频或流式播放。
 * @param url - 音频资源 URL。
 * @param options - 播放选项。
 * @returns 正在播放的 AudioBufferSourceNode。
 * @since 2.2.0
 * @example
 * ```ts
 * const result = await audio.playWebAudioFromUrl('https://example.com/audio.mp3');
 * if (result.isOk()) {
 *     const source = result.unwrap();
 * }
 * ```
 */
declare function playWebAudioFromUrl(url: string, options?: PlayOptions): AsyncIOResult<AudioBufferSourceNode>;

export { closeGlobalAudioContext, createWebAudioContext, getGlobalAudioContext, playWebAudioFromAudioBuffer, playWebAudioFromBufferSource, playWebAudioFromFile, playWebAudioFromUrl };
export type { PlayOptions };