/**
 * Audio Module - Audio playback and management system
 * 
 * Features:
 * - Audio playback with WAV files - Support for standard WAV audio format
 * - Audio streaming playback - Real-time audio stream processing
 * - Text-to-speech playback - TTS functionality for text conversion
 * - Volume control and range management - Precise volume control with range validation
 * - Playback interruption and cache management - Advanced playback control and resource management
 * 
 * Usage:
 * - Audio playback service - Background music, sound effects, notifications
 * - TTS service - Voice announcements, accessibility features (not all devices support)
 * - Volume management - System-wide volume control with user-friendly interface
 * - Support cross-thread audio playback
 * - The WAV format should be Channels : 1, Sample Rate : approximately 24000, Precision : 16-bit, other formats need to be converted to this format
 * 
 * Doc/Demo : https://github.com/DejaOS/DejaOS
 */
import { audioClass } from './libvbar-m-dxaudio.so'

// Create audio object instance for native operations
const audioObj = new audioClass();
// Export audio module interface
const audio = {}

// Playback status code constants
audio.PLAY_CODE = {
	SUCCESS: 0,        // Playback completed successfully
	FAILED: -1,        // Playback operation failed
	QUEUE_IS_FULL: -2  // Playback queue is full, cannot add more audio
}

// Language type constants for TTS functionality
audio.PLAY_TYPE = {
	CHINESE_DATA: 0,     /** Chinese language TTS data */
	ENGLISH_DATA: 1,     /** English language TTS data */
}

/**
 * Audio system initialization
 * @param {number} [volume=5] Volume level (0-10) - User-friendly volume range (0 means mute), default 5
 * @param {number} [periodSize=512] Period size in samples - Audio processing granularity, default 512
 * @param {number} [bufferSize=2048] Buffer size in samples - Audio buffer capacity, default 2048
 * @throws {Error} If initialization fails - Throws error when audio system cannot be initialized
 * 
 * Technical Details:
 * - periodSize: Controls audio processing latency. Smaller values (256,512) provide lower latency 
 *   but higher CPU usage. Larger values (1024,2048) reduce CPU usage but increase latency.
 * - bufferSize: Determines audio smoothness. Smaller values (1024,2048) use less memory but may 
 *   cause audio stuttering. Larger values (4096,8192) provide smoother playback but use more memory.
 * - Recommended configurations:
 *   * Low latency: (256, 1024) - For real-time communication
 *   * High quality: (1024, 4096) - For music playback
 *   * Balanced: (512, 2048) - For general applications
 */
audio.init = function (volume = 5, periodSize = 512, bufferSize = 2048) {
	// Parameter validation
	validateNumber(volume, 'volume');
	validateNumber(periodSize, 'periodSize');
	validateNumber(bufferSize, 'bufferSize');

	// Validate volume range (0-10 for user-friendly interface; 0 means mute)
	if (volume < 0 || volume > 10) {
		throw new Error("audio.init: 'volume' must be between 0 and 10");
	}

	// Initialize audio system with specified parameters
	audioObj.audioInit(volume, periodSize, bufferSize)
}

/**
 * Audio system deinitialization
 * @returns {boolean} true if deinitialization successful, false otherwise
 * 
 * Note: This function releases all audio resources and should be called
 * when the audio system is no longer needed to prevent resource leaks.
 */
audio.deinit = function () {
	return audioObj.audioDeinit()
}


/**
 * Get current audio volume level
 * @returns {number} Current volume level (0-10) - Mapped from hardware volume to user-friendly range (0 means mute)
 * 
 * The returned value is automatically mapped from the hardware volume range
 * to the user-friendly 1-10 range for consistent interface experience.
 */
audio.getVolume = function () {
	return audioObj.audioGetVolume()
}

/**
 * Set audio volume level
 * @param {number} volume Volume level (0-10), required parameter (0 means mute)
 * @returns {boolean} true if volume set successfully, false otherwise
 * 
 * Volume levels outside the valid range (1-10) will be automatically clamped
 * to the nearest valid value. The function maps user volume to hardware volume
 * internally for optimal audio quality.
 */
audio.setVolume = function (volume) {
	if (volume == undefined || volume == null) {
		throw new Error("audio.setVolume: 'volume' parameter should not be null")
	}
	if (volume < 0 || volume > 10) {
		throw new Error("audio.setVolume: 'volume' must be between 0 and 10")
	}
	return audioObj.audioSetVolume(volume)
}

/**
 * Play WAV audio file from file path
 * @param {string} path Absolute path to WAV file, required parameter
 * @returns {number} Playback status code (see audio.PLAY_CODE constants)
 * 
 * File path should start with '/app/code/' and typically placed in the project's
 * resource directory (same level as src directory). Supports standard WAV format.
 * 
 * Return values:
 * - 0: Playback started successfully
 * - -1: Playback failed
 * - -2: Playback queue is full
 */
audio.play = function (path) {
	if (!path) {
		throw new Error("audio.play: 'path' parameter should not be null")
	}
	return audioObj.audioPlayWav(path)
}

/**
 * Play audio from ArrayBuffer data (streaming audio)
 * @param {ArrayBuffer} buffer Audio data buffer, required parameter
 * @returns {number} Playback status code (see audio.PLAY_CODE constants)
 * 
 * This function is useful for playing audio streams, real-time audio data,
 * or audio data received from network sources. The buffer should contain
 * valid WAV format audio data.
 */
audio.playWavData = function (buffer) {
	if (!buffer) {
		throw new Error("audio.playWavData: 'buffer' parameter should not be null")
	}
	return audioObj.audioPlayWavData(buffer)
}

/**
 * Play text using Text-to-Speech (TTS) functionality
 * @param {string} txt Text to be converted to speech, required parameter
 * @param {number} type Language type, required parameter (0: Chinese, 1: English)
 * @returns {number} Playback status code (see audio.PLAY_CODE constants)
 * 
 * TTS functionality may not be supported on all devices. The function converts
 * the provided text to speech in the specified language and plays it through
 * the audio system.
 * 
 * Language types:
 * - 0: Chinese (中文)
 * - 1: English (English)
 */
audio.playTxt = function (txt, type) {
	if (!txt) {
		throw new Error("audio.playTxt: 'txt' parameter should not be null")
	}
	if (typeof type !== 'number' || isNaN(type)) {
		throw new Error("audio.playTxt: 'type' parameter should not be null")
	}
	return audioObj.audioPlayTxt(txt, type)
}

/**
 * Interrupt currently playing audio
 * @returns {boolean} true if interruption successful, false otherwise
 * 
 * This function immediately stops the currently playing audio without affecting
 * the playback queue. It's useful for emergency stops or when switching
 * between different audio sources.
 */
audio.interrupt = function () {
	return audioObj.audioPlayingInterrupt()
}

/**
 * Clear audio playback cache and queue
 * @returns {boolean} true if cache cleared successfully, false otherwise
 * 
 * This function removes all pending audio from the playback queue and clears
 * the audio cache. It should be used when you want to completely reset the
 * audio playback state or free up memory resources.
 * 
 * Note: This operation is mutually exclusive with playback functions and
 * should not be called while audio is actively playing.
 */
audio.clearCache = function () {
	return audioObj.audioClearPlayCache()
}


function validateNumber(value, name) {
	if (typeof value !== 'number' || isNaN(value)) {
		throw new TypeError(`${name} must be a valid number`);
	}
}

// Export audio module as default export
export default audio;