spotube/node-mpv.d.ts

// Type definitions for node-mpv 2.0-beta.0
// Project: node-mpv <https://github.com/j-holub/Node-MPV>
// Definitions by: leonekmi <me@leonekmi.fr>

declare module "node-mpv" {
  import EventEmitter = NodeJS.EventEmitter;

  interface NodeMpvOptions {
    // Print debug lines
    debug?: boolean;
    // Print more lines
    verbose?: boolean;
    // Specify socket
    socket?: string;
    // Don't open video display
    audio_only?: boolean;
    // Auto-restart on a crash
    auto_restart?: boolean;
    // Time update for timeposition event
    time_update?: number;
    // Path to mpv binary
    binary?: string;
  }

  /*interface NodeMpvError {

}*/

  // these are the emitted events
  type EventNames = "crashed" | "getrequest" | "seek" | "started" | "stopped" | "paused" | "resumed" | "status" | "timeposition" | "quit";
  type VoidCallback = () => void;
  type VoidCallbackWithData<ArgType> = (arg: ArgType) => void;
  type VoidCallbackWithData2<ArgType, ArgType2> = (arg: ArgType, arg2: ArgType2) => void;

  type LoadMode = "replace" | "append";
  type MediaLoadMode = LoadMode | "append-play";
  type AudioFlag = "select" | "auto" | "cached";
  type SeekMode = "relative" | "absolute";
  type RepeatMode = number | "inf" | "no";
  type PlaylistMode = "weak" | "force";

  interface TimePosition {
    start: number;
    end: number;
  }
  type StatusObjectProperties = "mute" | "pause" | "duration" | "volume" | "filename" | "path" | "media-title" | "playlist-pos" | "playlist-count" | "loop" | "fullscreen" | "sub-visibility";

  interface StatusObject {
    property: StatusObjectProperties;
    value: string | number | boolean;
  }

  type EventListenerArgs<EventName extends EventNames> = [EventName, VoidCallback];
  type EventListenerArgsWithData<EventName extends EventNames, DataType> = [EventName, VoidCallbackWithData<DataType>];
  type EventListenerArgsWithMultipleData<EventName extends EventNames, DataType, DataType1> = [EventName, VoidCallbackWithData2<DataType, DataType1>];

  export default class NodeMpv implements EventEmitter {
    /**
     * Listen to certain events which are emitted after any kind of
     * status change of mpv player.
     * @param args
     * @see for Events https://github.com/j-holub/Node-MPV#events
     */

    addListener(...args: EventListenerArgs<"crashed">): this;
    addListener(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    addListener(...args: EventListenerArgs<"paused">): this;
    addListener(...args: EventListenerArgs<"quit">): this;
    addListener(...args: EventListenerArgs<"resumed">): this;
    addListener(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    addListener(...args: EventListenerArgs<"started">): this;
    addListener(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    addListener(...args: EventListenerArgs<"stopped">): this;
    addListener(...args: EventListenerArgsWithData<"timeposition", number>): this;

    /**
     * Listen to certain events which are emitted after any kind of
     * status change of mpv player
     * @param args
     * @see for Events https://github.com/j-holub/Node-MPV#events
     */
    on(...args: EventListenerArgs<"crashed">): this;
    on(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    on(...args: EventListenerArgs<"paused">): this;
    on(...args: EventListenerArgs<"quit">): this;
    on(...args: EventListenerArgs<"resumed">): this;
    on(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    on(...args: EventListenerArgs<"started">): this;
    on(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    on(...args: EventListenerArgs<"stopped">): this;
    on(...args: EventListenerArgsWithData<"timeposition", number>): this;

    /**
     * Listen to certain events which are emitted after any kind of
     * status change of mpv player
     * @param args
     * @see for Events https://github.com/j-holub/Node-MPV#events
     */
    once(...args: EventListenerArgs<"crashed">): this;
    once(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    once(...args: EventListenerArgs<"paused">): this;
    once(...args: EventListenerArgs<"quit">): this;
    once(...args: EventListenerArgs<"resumed">): this;
    once(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    once(...args: EventListenerArgs<"started">): this;
    once(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    once(...args: EventListenerArgs<"stopped">): this;
    once(...args: EventListenerArgsWithData<"timeposition", number>): this;

    /**
     * Remove listener that is listening to the provided event `eventName`
     * @param args
     */
    off(...args: EventListenerArgs<"crashed">): this;
    off(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    off(...args: EventListenerArgs<"paused">): this;
    off(...args: EventListenerArgs<"quit">): this;
    off(...args: EventListenerArgs<"resumed">): this;
    off(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    off(...args: EventListenerArgs<"started">): this;
    off(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    off(...args: EventListenerArgs<"stopped">): this;
    off(...args: EventListenerArgsWithData<"timeposition", number>): this;

    /**
     * Remove listener that is listening to the provided event `eventName`
     * @param args
     */
    removeListener(...args: EventListenerArgs<"crashed">): this;
    removeListener(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    removeListener(...args: EventListenerArgs<"paused">): this;
    removeListener(...args: EventListenerArgs<"quit">): this;
    removeListener(...args: EventListenerArgs<"resumed">): this;
    removeListener(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    removeListener(...args: EventListenerArgs<"started">): this;
    removeListener(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    removeListener(...args: EventListenerArgs<"stopped">): this;
    removeListener(...args: EventListenerArgsWithData<"timeposition", number>): this;

    /**
     * Removes all listeners listening to a particular event `eventName`
     * @param {EventNames?} event - Event names
     */

    removeAllListeners(event?: EventNames): this;

    setMaxListeners(n: number): this;

    getMaxListeners(): number;

    listeners(event: EventNames): Function[];

    rawListeners(event: EventNames): Function[];
    emit(event: EventNames, ...args: any[]): boolean;
    listenerCount(event: EventNames): number;
    // Added in Node 6...
    prependListener(...args: EventListenerArgs<"crashed">): this;
    prependListener(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    prependListener(...args: EventListenerArgs<"paused">): this;
    prependListener(...args: EventListenerArgs<"quit">): this;
    prependListener(...args: EventListenerArgs<"resumed">): this;
    prependListener(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    prependListener(...args: EventListenerArgs<"started">): this;
    prependListener(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    prependListener(...args: EventListenerArgs<"stopped">): this;
    prependListener(...args: EventListenerArgsWithData<"timeposition", number>): this;

    prependOnceListener(...args: EventListenerArgs<"crashed">): this;
    prependOnceListener(...args: EventListenerArgsWithMultipleData<"getrequest", string, any>): this;
    prependOnceListener(...args: EventListenerArgs<"paused">): this;
    prependOnceListener(...args: EventListenerArgs<"quit">): this;
    prependOnceListener(...args: EventListenerArgs<"resumed">): this;
    prependOnceListener(...args: EventListenerArgsWithData<"seek", TimePosition>): this;
    prependOnceListener(...args: EventListenerArgs<"started">): this;
    prependOnceListener(...args: EventListenerArgsWithData<"status", StatusObject>): this;
    prependOnceListener(...args: EventListenerArgs<"stopped">): this;
    prependOnceListener(...args: EventListenerArgsWithData<"timeposition", number>): this;

    eventNames(): Array<string | symbol>;

    /**
     * A mpv wrapper for node
     *
     * @param options - Tweak NodeMPV behaviour
     * @param mpv_args - Arrays of CLI options to pass to mpv. IPC options are automatically appended.
     */
    constructor(options?: NodeMpvOptions, mpv_args?: string[]);

    /**
     * Loads a file into MPV
     *
     * @param source - Path to the media file
     * @param mode
     * `replace`: replace the current media
     *
     * `append`: Append at the end of the playlist
     *
     * `append-play`: Append after the current song
     * @param options - Options formatted as option=label
     */
    load(source: string, mode?: MediaLoadMode, options?: string[]): Promise<void>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_audio.js
    /**
     * Add an audio track to the media file
     *
     * @param file - Path to the audio track
     * @param flag - Flag to use (select, auto, cached)
     * @param title - Title in OSD/OSC
     * @param lang - Language
     */
    addAudioTrack(file: string, flag?: AudioFlag, title?: string, lang?: string): Promise<void>;

    /**
     * Remove an audio track based on its id.
     *
     * @param id - ID of the audio track to remove
     */
    removeAudioTrack(id: number): Promise<void>;

    /**
     * Select an audio track based on its id.
     *
     * @param id - ID of the audio track to select
     */
    selectAudioTrack(id: number): Promise<void>;

    /**
     * Cycles through the audio track
     */
    cycleAudioTracks(): Promise<void>;

    /**
     * Adjust audio timing
     * @param seconds - Delay in seconds
     */
    adjustAudioTiming(seconds: number): Promise<void>;

    /**
     * Set playback speed
     * @param factor - 0.1 - 100: percentage of playback speed
     */
    speed(factor: number): Promise<void>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_controls.js
    /**
     * Toggle play/pause
     */
    togglePause(): Promise<void>;

    /**
     * Pauses playback
     */
    pause(): Promise<void>;

    /**
     * Resumes playback
     */
    resume(): Promise<void>;

    /**
     * Play the file in playlist
     */
    play(): Promise<void>;

    /**
     * Stop playback immediately
     */
    stop(): Promise<void>;

    /**
     * Set volume
     *
     * @param volume
     */
    volume(volume: number): Promise<void>;

    /**
     * Increase/Decrease volume
     *
     * @param volume
     */
    adjustVolume(volume: number): Promise<void>;

    /**
     * Mute
     *
     * @param set - setMute, if not specified, cycles
     */
    mute(set?: boolean): Promise<void>;

    /**
     * Seek
     *
     * @param seconds - Seconds
     * @param mode - Relative, absolute
     * @see for info about seek https://mpv.io/manual/stable/#command-interface-seek-%3Ctarget%3E-[%3Cflags%3E]
     */
    seek(seconds: number, mode?: SeekMode): Promise<void>;

    /**
     * Shorthand for absolute seek
     *
     * @param seconds - Seconds
     */
    goToPosition(seconds: number): Promise<void>;

    /**
     * Set loop mode for current file
     *
     * @param times - either a number of loop iterations, 'inf' for infinite loop or 'no' to disable loop.
     * If it's not specified, the property will cycle through inf and no.
     */
    loop(times?: RepeatMode): Promise<void>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_commands.js
    // List of mpv properties are available here: https://mpv.io/manual/stable/#property-list
    /**
     * Retrieve a property
     *
     * @param property
     */
    getProperty(property: string): Promise<string>;

    /**
     * Set a property
     *
     * @param property
     * @param value
     */
    setProperty(property: string, value: any): Promise<void>;

    /**
     * Set a set of properties
     *
     * @param properties - {property1: value1, property2: value2}
     */
    setMultipleProperties(properties: object): Promise<void>;

    /**
     * Add value to a property (only on number properties)
     *
     * @param property
     * @param value
     */
    addProperty(property: string, value: number): Promise<void>;
    /**
     * Multiply a property by value (only on number properties)
     *
     * @param property
     * @param value
     */
    multiplyProperty(property: string, value: number): Promise<void>;

    /**
     * Cycle through different modes of a property (boolean, enum)
     *
     * @param property
     */
    cycleProperty(property: string): Promise<void>;

    /**
     * Send a custom command to mpv
     *
     * @param command Command name
     * @param args Array of arguments
     */
    command(command: string, args: string[]): Promise<void>;

    /**
     * Send a custom payload to mpv
     *
     * @param command the JSON command to send to mpv
     */
    commandJSON(command: object): Promise<void>;

    /**
     * Send a custom payload to mpv (no JSON encode)
     *
     * @param command the JSON encoded command to send to mpv
     */
    freeCommand(command: string): Promise<void>;

    /**
     * Observe a property
     * You can receive events with the 'status' event
     *
     * @param property The property to observe
     */
    observeProperty(property: string): any;

    /**
     * Unobserve a property
     *
     * @param property
     */
    unobserveProperty(property: string): any;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_information.js
    /**
     * Returns the mute status of mpv
     */
    isMuted(): Promise<boolean>;

    /**
     * Returns the pause status of mpv
     */
    isPaused(): Promise<boolean>;

    /**
     * Returns the seekable property of the loaded media
     * Some medias are not seekable (livestream, unbuffered media)
     */
    isSeekable(): Promise<boolean>;

    /**
     * Retrieve the duration of the loaded media
     */
    getDuration(): Promise<number>;

    /**
     * Retrieve the current time position of the loaded media
     */
    getTimePosition(): Promise<number>;

    /**
     * Retrieve the current time position (in percentage) of the loaded media
     */
    getPercentPosition(): Promise<number>;

    /**
     * Retrieve the time remaining of the loaded media
     */
    getTimeRemaining(): Promise<number>;

    /**
     * Retrieve the metadata of the loaded media
     */
    getMetadata(): Promise<object>;

    /**
     * Retrieve the title of the loaded media
     */
    getTitle(): Promise<string>;

    /**
     * Retrieve the artist of the loaded media
     */
    getArtist(): Promise<string>;

    /**
     * Retrieve the album of the loaded media
     */
    getAlbum(): Promise<string>;

    /**
     * Retrieve the year of the loaded media
     */
    getYear(): Promise<number>;

    /**
     * Retrieve the filename of the loaded media
     *
     * @param format 'stripped' remove the extension, default to 'full'
     */
    getFilename(format?: "full" | "stripped"): Promise<string>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_playlist.js
    /**
     * Load a playlist file
     *
     * @param playlist Path to the playlist file
     * @param mode 'append' adds the playlist to the existing one. Defaults to 'replace'
     */
    loadPlaylist(playlist: string, mode?: LoadMode): Promise<void>;

    /**
     * Add a song to the playlist
     *
     * @param source File path of media
     * @param mode
     * replace: replace the current media
     * append: Append at the end of the playlist
     * append-play: Append after the current song
     * @param options
     */
    append(source: string, mode?: MediaLoadMode, options?: string[]): Promise<void>;

    /**
     * Load next element in playlist
     *
     * @param mode - 'force' may go into an undefined index of the playlist
     */
    next(mode?: PlaylistMode): Promise<void>;

    /**
     * Load previous element in playlist
     *
     * @param mode - 'force' may go into an undefined index of the playlist
     */
    prev(mode?: PlaylistMode): Promise<void>;

    /**
     * Jump to position in playlist
     *
     * @param position
     */
    jump(position: number): Promise<void>;

    /**
     * Empty the playlist
     */
    clearPlaylist(): Promise<void>;

    /**
     *
     * @param index
     */
    playlistRemove(index: number): Promise<void>;

    /**
     *
     * @param index1
     * @param index2
     */
    playlistMove(index1: number, index2: number): Promise<void>;

    /**
     *
     */
    shuffle(): Promise<void>;

    /**
     *
     */
    getPlaylistSize(): Promise<number>;

    /**
     *
     */
    getPlaylistPosition(): Promise<number>;

    /**
     *
     */
    getPlaylistPosition1(): Promise<number>;

    /**
     * Set loop mode for playlist
     *
     * @param times - either a number of loop iterations, 'inf' for infinite loop or 'no' to disable loop.
     * If it's not specified, the property will cycle through inf and no.
     */
    loopPlaylist(times?: RepeatMode): Promise<void>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_startStop.js
    /**
     * Starts mpv, by spawning a child process or by attaching to existing socket
     */
    start(): Promise<void>;
    /**
     * Closes mpv
     *
     * [Important!] Calling method `quit` doesn't trigger the event `quit`
     */
    quit(): Promise<void>;
    /**
     * Returns the status of mpv
     */
    isRunning(): boolean;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_subtitle.js
    /**
     * Loads a subtitle file into the current media file
     *
     * @param file Path to the subtitle file
     * @param flag
     * Select: Select the loaded file
     * Auto: Let mpv decide
     * Cached: Don't select the loaded file
     * @param title Title to show in OSD/OSC
     * @param lang Language of the subtitles
     */
    addSubtitles(file: string, flag?: "select" | "auto" | "cached", title?: string, lang?: string): Promise<void>;

    /**
     * Remove subtitles
     *
     * @param id Index of subtitles to delete
     */
    removeSubtitles(id: number): Promise<void>;

    /**
     * Cycle through available subtitles
     */
    cycleSubtitles(): Promise<void>;

    /**
     * Select subtitles by its id
     *
     * @param id
     */
    selectSubtitles(id: number): Promise<void>;

    /**
     * Toggle subtitles visibility
     */
    toggleSubtitleVisibility(): Promise<void>;

    /**
     * Show the subtitles on the screen
     */
    showSubtitles(): Promise<void>;

    /**
     * Hide the subtitles on the screen
     */
    hideSubtitles(): Promise<void>;

    /**
     * Adjust the subtitles offset to seconds
     *
     * @param seconds Offset to apply in seconds
     */
    adjustSubtitleTiming(seconds: number): Promise<void>;

    /**
     * Seek based on subtitles lines
     *
     * @param lines
     */
    subtitleSeek(lines: number): Promise<void>;

    /**
     * Scale the font of subtitles based on scale
     *
     * @param scale
     */
    subtitleScale(scale: number): Promise<void>;

    /**
     * Show a text using ASS renderer
     *
     * @param ass an ass string
     * @param duration duration in seconds
     * @param position ASS alignment
     */
    displayASS(ass: string, duration: number, position?: number): Promise<void>;

    // https://github.com/j-holub/Node-MPV/blob/master/lib/mpv/_video.js
    /**
     * Enter fullscreen
     */
    fullscreen(): Promise<void>;

    /**
     * Leave fullscreen
     */
    leaveFullscreen(): Promise<void>;

    /**
     * Toggle fullscreen
     */
    toggleFullscreen(): Promise<void>;

    /**
     * Take a screenshot
     *
     * @param file
     * @param option
     * Subtitles: show subtitles
     * Video: hide subtitles/osd/osc
     * Window: Take the screen at the size of the window
     */
    screenshot(file: string, option: "subtitles" | "video" | "window"): Promise<void>;

    /**
     * Rotate the video
     *
     * @param degrees
     */
    rotateVideo(degrees: number): Promise<void>;

    /**
     * Zoom the video, 0 means no zoom, 1 means x2
     *
     * @param factor
     */
    zoomVideo(factor: number): Promise<void>;

    /**
     * Set Brightness
     *
     * @param value
     */
    brightness(value: number): Promise<void>;

    /**
     * Set Contrast
     *
     * @param value
     */
    contrast(value: number): Promise<void>;

    /**
     * Set saturation
     *
     * @param value
     */
    saturation(value: number): Promise<void>;

    /**
     * Set gamme on media
     *
     * @param value
     */
    gamma(value: number): Promise<void>;

    /**
     * Set Hue
     *
     * @param value
     */
    hue(value: number): Promise<void>;
  }
}