Interface Utils

The Utils interface provides utility methods for various operations such as file manipulation, executing external programs, and interacting with the system.

Available In Entry

Main and Global entry

Hierarchy

  • Utils

Properties

ERROR_BINARY_NOT_FOUND: -1

The error code returned by utils.exec when the executable file is not found.

ERROR_RUNTIME: -2

The error code returned by utils.exec when the executable file is found but cannot be executed.

Methods

  • Check if a binary file exists in the system PATH, or a file exists at the given path. This method can be used before utils.exec to check if the executable file exists.

    Example

    // check if ffmpeg exists in PATH
    utils.fileInPath("ffmpeg")

    // check if a ffmpeg exists in the plugin's data directory
    utils.fileInPath("@data/bin/ffmpeg")

    Parameters

    • file: string

      The binary name, or the path to the file.

    Returns boolean

  • Resolve a path by expanding special path prefixes like @data to the actual system directory. It also handles tilde expansion.

    Parameters

    • path: string

      The path to resolve.

    Returns string

  • Execute an external program.

    Returns

    A promise that resolves to an object containing the exit status, standard output, and standard error output.

    Remarks

    Permission "file-system" must be present in Info.json to use this method.

    Example

    // execute ffmpeg
    const { status, stdout, stderr } = await utils.exec("ffmpeg", [
    "-i", "input.mp4",
    "-vf", "scale=1280:720",
    "output.mp4",
    ]);

    Parameters

    • file: string

      The binary name (if it's in the system PATH), or the path to the executable file. It's recommended to use utils.fileInPath to check if the executable file exists.

    • args: string[]

      The arguments to pass to the executable file.

    • Optional cwd: string

      The working directory of the executable file.

    • Optional stdoutHook: ((data: string) => void)

      Set up a hook to receive the streaming standard output of the executable file.

        • (data: string): void
        • Parameters

          • data: string

            The newly available standard output data.

          Returns void

    • Optional stderrHook: ((data: string) => void)

      Set up a hook to receive the streaming standard error of the executable file.

        • (data: string): void
        • Parameters

          • data: string

            The newly available standard error data.

          Returns void

    Returns Promise<{
        status: number;
        stdout: string;
        stderr: string;
    }>

  • Show a system dialog with "OK" and "Cancel" buttons. Can be used to ask for confirmation or simply show a message to the user.

    Returns

    true if the user clicks "OK", false if the user clicks "Cancel".

    Example

    const yes = utils.ask("Are you sure you want to delete these files?");

    utils.ask("This is a message");

    Parameters

    • title: string

      The content of the dialog.

    Returns boolean

  • Show a system dialog with an input field to prompt the user for a string input.

    Example

    // download a file to the plugin's data folder with user-input filename
    const fn = utils.prompt("Please enter the file name");
    http.download("https://example.com/test.zip", `@data/downloads/${fn}`);

    Parameters

    • title: string

      The title of the dialog.

    Returns string

  • Show a system file chooser panel.

    Returns

    Full path of the chosen file or directory.

    Example

    const path = utils.chooseFile("Please select a subtitle file", {
    allowedFileTypes: ["ass", "srt"],
    });
    core.subtitle.loadTrack(path);

    Parameters

    • title: string

      The title of the panel.

    • options: Partial<{
          chooseDir: boolean;
          allowedFileTypes: string[];
      }>

      Optional options.

      • chooseDir: choose a directory instead of a file.
      • allowedFileTypes: specify a list of available file extensions. Files without these extensions will be disabled in the panel.

    Returns string

  • Write a password to the system keychain. Can be used to store other sensitive information such as JWT tokens.

    Returns

    true if the password is written successfully, false otherwise.

    Parameters

    • service: string

      The service name. It will be prefixed by the plugin's identifier.

    • name: string

      The username.

    • password: string

      The password to write.

    Returns boolean

  • Read a password corresponding to the username from the system keychain.

    Returns

    The password if read successfully, false otherwise.

    Parameters

    • service: string

      The service name.

    • name: string

      The usaername.

    Returns string | false

  • Open a URL in the system. It can be a http or https link, or a file path. When it is a web URL, the default browser will be used to open the link. When it is a file path, magic variables like @data will be resolved, and the file will be revealed in Finder.

    Returns

    true if the URL is opened successfully, false otherwise.

    Parameters

    • url: string

      The URL to open.

    Returns boolean

Generated using TypeDoc