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

Index

Properties

ERROR_BINARY_NOT_FOUND ERROR_RUNTIME

Methods

fileInPath resolvePath exec ask prompt chooseFile keyChainWrite keyChainRead open

Properties

ERROR_BINARY_NOT_FOUND

ERROR_BINARY_NOT_FOUND: -1

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

ERROR_RUNTIME

ERROR_RUNTIME: -2

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

Methods

fileInPath

fileInPath(file: string): boolean
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
- Defined in index.d.ts:1680

resolvePath

resolvePath(path: string): string
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
- Defined in index.d.ts:1686

exec

exec(file: string, args: string[], cwd?: string, stdoutHook?: ((data: string) => void), stderrHook?: ((data: string) => void)): Promise<{
    status: number;
    stdout: string;
    stderr: 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;
}>
- Defined in index.d.ts:1708

ask

ask(title: string): boolean
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
- Defined in index.d.ts:1742

prompt

prompt(title: string): string

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

chooseFile

chooseFile(title: string, options: Partial<{
chooseDir: boolean;
allowedFileTypes: string[];
}>): 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
- Defined in index.d.ts:1772

keyChainWrite

keyChainWrite(service: string, name: string, password: string): boolean
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
- Defined in index.d.ts:1787

keyChainRead

keyChainRead(service: string, name: string): string | false
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
- Defined in index.d.ts:1794

open

open(url: string): boolean
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
- Defined in index.d.ts:1802

Interface Utils

Available In Entry

Hierarchy

Index

Properties

Methods

Properties

ERROR_BINARY_NOT_FOUND

ERROR_RUNTIME

Methods

fileInPath

Example

Parameters

file: string

Returns boolean

resolvePath

Parameters

path: string

Returns string

exec

Returns

Remarks

Example

Parameters

file: string

args: string[]

Optional cwd: string

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

Parameters

data: string

Returns void

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

Parameters

data: string

Returns void

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

ask

Returns

Example

Parameters

title: string

Returns boolean

prompt

Example

Parameters

title: string

Returns string

chooseFile

Returns

Example

Parameters

title: string

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

Returns string

keyChainWrite

Returns

Parameters

service: string

name: string

password: string

Returns boolean

keyChainRead

Returns

Parameters

service: string

name: string

Returns string | false

open

Returns

Parameters

url: string

Returns boolean

Settings

Member Visibility

Theme

`Optional` cwd: string

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

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

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

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