tauri-plugin-mpv-api/dist-js/index.d.ts

A Tauri plugin for embedding the mpv player in your app via JSON IPC.

import { UnlistenFn } from '@tauri-apps/api/event';
import type { MpvCommand, VideoMarginRatio, MpvConfig, MpvEvent, MpvCommandResponse, MpvPropertyEventFor, MpvPropertyValue } from './types';
export * from './types';
export declare const COMMON_PROPERTIES: readonly ["playlist", "filename", "pause", "eof-reached", "time-pos", "duration", "volume", "mute", "speed"];
export declare const DEFAULT_MPV_CONFIG: MpvConfig;
/**
 * Initialize mpv player.
 *
 * @param {MpvConfig} [mpvConfig] - Initialization options.
 * @param {string} [windowLabel] - The label of the target window. Defaults to the current window's label.
 * @returns {Promise<string>} A promise that resolves with the actual window label used for initialization.
 * @throws {Error} Throws an error if mpv initialization fails (e.g., mpv executable not in PATH).
 *
 * @example
 * ```typescript
 * import { init, destroy, MpvConfig } from 'tauri-plugin-mpv-api';
 *
 * // Properties to observe
 * const OBSERVED_PROPERTIES = ['pause', 'time-pos', 'duration', 'filename'] as const;
 *
 * // mpv configuration
 * const mpvConfig: MpvConfig = {
 *   args: [
 *     '--vo=gpu-next',
 *     '--hwdec=auto-safe',
 *     '--keep-open=yes',
 *     '--force-window',
 *   ],
 *   observedProperties: OBSERVED_PROPERTIES,
 * };
 *
 * // Initialize mpv
 * try {
 *   await init(mpvConfig);
 * } catch (error) {
 *   console.error('Failed to initialize mpv:', error);
 * }
 *
 * // Destroy mpv when no longer needed
 * await destroy();
 * ```
 */
export declare function init(mpvConfig?: MpvConfig, windowLabel?: string): Promise<string>;
/**
 * @deprecated Use `init()` instead. This function will be removed in a future version.
 */
export declare const initializeMpv: typeof init;
/**
 * Destroy mpv player.
 *
 * @param {string} [windowLabel] - Target window label, defaults to current window
 * @returns {Promise<void>} A promise that resolves when the operation completes.
 *
 * @example
 * ```typescript
 * import { destroy } from 'tauri-plugin-mpv-api';
 *
 * await destroy();
 * ```
 */
export declare function destroy(windowLabel?: string): Promise<void>;
/**
 * @deprecated Use `destroy()` instead. This function will be removed in a future version.
 */
export declare const destroyMpv: typeof destroy;
/**
 * Listen to mpv property change events.
 *
 * @param {readonly string[]} properties - Properties to observe
 * @param {function} callback - Function to call when mpv events are received
 * @param {string} [windowLabel] - Target window label, defaults to current window
 * @returns {Promise<UnlistenFn>} Function to call to stop listening
 *
 * @example
 * ```typescript
 * import { observeMpvProperties } from 'tauri-plugin-mpv-api';
 *
 * const OBSERVED_PROPERTIES = ['pause', 'time-pos', 'duration', 'filename'] as const;
 *
 * // Observe properties
 * const unlisten = await observeMpvProperties(
 *   OBSERVED_PROPERTIES,
 *   ({ name, data }) => {
 *     switch (name) {
 *       case 'pause':
 *         console.log('Playback paused state:', data);
 *         break;
 *       case 'time-pos':
 *         console.log('Current time position:', data);
 *         break;
 *       case 'duration':
 *         console.log('Duration:', data);
 *         break;
 *       case 'filename':
 *         console.log('Current playing file:', data);
 *         break;
 *     }
 *   });
 *
 * // Unlisten when no longer needed
 * unlisten();
 * ```
 */
export declare function observeMpvProperties<T extends ReadonlyArray<string>>(properties: T, callback: (event: MpvPropertyEventFor<T[number]>) => void, windowLabel?: string): Promise<UnlistenFn>;
/**
 * Listen to mpv property change events with common properties
 *
 * @param {function} callback - Function to call when mpv events are received
 * @param {string} [windowLabel] - Target window label, defaults to current window
 * @returns {Promise<UnlistenFn>} Function to call to stop listening
 *
 * @example
 * ```typescript
 * import { observeMpvProperties } from 'tauri-plugin-mpv-api';
 *
 * // Observe properties
 * const unlisten = await observeMpvProperties(
 *   ({ name, data }) => {
 *     switch (name) {
 *       case 'pause':
 *         console.log('Playback paused state:', data);
 *         break;
 *       case 'time-pos':
 *         console.log('Current time position:', data);
 *         break;
 *       case 'duration':
 *         console.log('Duration:', data);
 *         break;
 *       case 'filename':
 *         console.log('Current playing file:', data);
 *         break;
 *     }
 *   });
 *
 * // Unlisten when no longer needed
 * unlisten();
 * ```
 */
export declare function observeMpvProperties(callback: (event: MpvPropertyEventFor<typeof COMMON_PROPERTIES[number]>) => void, windowLabel?: string): Promise<UnlistenFn>;
/**
 * Listen to all mpv events.
 *
 * @param {(event: MpvEvent) => void} callback - Function to call when mpv events are received
 * @param {string} [windowLabel] - Target window label, defaults to current window
 * @returns {Promise<UnlistenFn>} Function to call to stop listening
 *
 * @example
 * ```typescript
 * import { listenMpvEvents } from 'tauri-plugin-mpv-api';
 *
 * // Listen events
 * const unlisten = await listenMpvEvents((mpvEvent) => {
 *   if (mpvEvent.event === 'property-change') {
 *     const { name, data } = mpvEvent
 *     switch (name) {
 *       case 'pause':
 *         console.log('Playback paused state:', data);
 *         break;
 *       case 'time-pos':
 *         console.log('Current time position:', data);
 *         break;
 *       case 'duration':
 *         console.log('Duration:', data);
 *         break;
 *       case 'filename':
 *         console.log('Current playing file:', data);
 *         break;
 *     }
 *   }
 * });
 *
 * // Unlisten when no longer needed
 * unlisten();
 * ```
 */
export declare function listenMpvEvents(callback: (event: MpvEvent) => void, windowLabel?: string): Promise<UnlistenFn>;
/**
 * Sends a command to mpv and returns only the `data` portion of the response.
 * This is a convenient shortcut for commands where you only need the return value.
 *
 * @param name The name of the command to execute.
 * @param args (Optional) An array of arguments for the command.
 * @param windowLabel (Optional) The label of the Tauri window to target. Defaults to the current window.
 * @returns A promise that resolves with the data returned by mpv.
 * @throws {Error} Throws an error if the mpv command fails.
 *
 * @example
 * ```typescript
 * import { command } from 'tauri-plugin-mpv-api';
 *
 * // Get the duration property
 * const duration = await command('get_property', ['duration']);
 * console.log('Duration is:', duration);
 *
 * // Seek 10 seconds forward (args are optional)
 * await command('seek', [10, 'relative']);
 *
 * // Pause the player (no args needed)
 * await command('cycle', ['pause']);
 * ```
 */
export declare function command(name: string, args?: unknown[], windowLabel?: string): Promise<unknown>;
/**
 * Sends a command to mpv without arguments and returns the `data` portion of the response.
 *
 * @param name The name of the command to execute.
 * @param windowLabel (Optional) The label of the Tauri window to target. Defaults to the current window.
 * @returns A promise that resolves with the data returned by mpv.
 * @throws {Error} Throws an error if the mpv command fails.
 */
export declare function command(name: string, windowLabel?: string): Promise<unknown>;
/**
 * Sends a command to mpv using original JSON IPC object structure.
 *
 * @param mpvCommand The command object to send to mpv.
 * @param windowLabel (Optional) The label of the Tauri window to target. Defaults to the current window.
 * @returns A promise that resolves with the full response object from mpv.
 * @throws {Error} Throws an error if the command fails or mpv returns an error status.
 * @see {@link https://mpv.io/manual/master/#json-ipc} for a full list of commands.
 *
 * @example
 * ```typescript
 * import { command } from 'tauri-plugin-mpv-api';
 *
 * // Load a file and check the full response
 * const response = await command({ command: ['loadfile', '/path/to/video.mp4'] });
 * if (response.error === 'success') {
 * console.log('File loaded successfully');
 * }
 *
 * // Seek with a custom request_id for tracking
 * const seekResponse = await command({ command: ['seek', 10, 'relative'], request_id: 999 });
 * console.log('Seek command with ID', seekResponse.request_id, 'was successful.');
 * ```
 */
export declare function command(mpvCommand: MpvCommand, windowLabel?: string): Promise<MpvCommandResponse>;
/**
 * @deprecated Use `command()` instead. This function will be removed in a future version.
 */
export declare const sendMpvCommand: typeof command;
/**
 * Gets the value of an mpv property.
 *
 * @param name The name of the property to get.
 * @param windowLabel (Optional) The label of the Tauri window to target.
 * @returns A promise that resolves with the typed property value.
 * @throws {Error} Throws an error if the command fails.
 *
 * @example
 * ```typescript
 * import { getProperty } from 'tauri-plugin-mpv-api';
 *
 * // Get volume
 * const volume = await getProperty('volume');
 *
 * // `custom` is now treated as `string`
 * const custom = await getProperty<string>('my-custom-property');
 * ```
 */
export declare function getProperty<T = never, K extends string = string>(name: K, windowLabel?: string): Promise<[T] extends [never] ? MpvPropertyValue<K> : T>;
/**
 * Sets the value of an mpv property.
 *
 * @param name The name of the property to set.
 * @param value The value to set. Must match the property's type if it is known.
 * @param windowLabel (Optional) The label of the Tauri window to target.
 * @returns A promise that resolves when the property has been set.
 * @throws {Error} Throws an error if the command fails.
 *
 * @example
 * ```typescript
 * import { setProperty } from 'tauri-plugin-mpv-api';
 *
 * // Set volume
 * await setProperty('volume', 80);
 *
 * // Explicitly provide a type for a custom or unknown property
 * await setProperty<string>('my-custom-property', 'some-value');
 * ```
 */
export declare function setProperty<T = never, K extends string = string>(name: K, value: [T] extends [never] ? MpvPropertyValue<K> : T, windowLabel?: string): Promise<void>;
/**
 * Set video margin ratio
 *
 * @param {VideoMarginRatio} ratio - Margin ratio configuration object
 * @param {string} [windowLabel] - Target window label, defaults to current window
 * @returns {Promise<void>} Promise with no return value
 * @throws {Error} Throws error when setting fails
 *
 * @example
 * ```typescript
 * import { setVideoMarginRatio } from 'tauri-plugin-mpv-api';
 *
 * // Leave 10% space at bottom for control bar
 * await setVideoMarginRatio({ bottom: 0.1 });
 *
 * // Leave margins on all sides
 * await setVideoMarginRatio({
 *   left: 0.05,
 *   right: 0.05,
 *   top: 0.1,
 *   bottom: 0.15,
 * });
 *
 * // Reset margins (remove all margins)
 * await setVideoMarginRatio({
 *   left: 0,
 *   right: 0,
 *   top: 0,
 *   bottom: 0,
 * });
 * ```
 */
export declare function setVideoMarginRatio(ratio: VideoMarginRatio, windowLabel?: string): Promise<void>;