suchmusic 宿主 API 参考

插件通过全局对象 suchmusic 调用宿主提供的能力。所有 API 调用前需确保已在 permissions 中声明对应权限，否则调用将抛出权限错误。

API 总览

API	所需权限	敏感操作	说明
`execProgram(path, args)`	`local_program`	是	调用本地可执行程序
`execTerminal(command)`	`local_program`	是	执行终端命令
`fileOp(operation, ...args)`	`file_system`	是	本地文件读写操作
`fetch(url, options?)`	`fetch`	否	HTTP 网络请求
`downloadFile(url, destPath)`	`fetch` + `file_system`	是	下载文件到本地
`writeMeta(filePath, tags)`	`file_system`	是	写入音乐文件元数据
`getSetting(key)`	`app_info`	否	读取 Such 应用设置
`createPlaylist(name, tracks)`	`playlist`	否	创建歌单
`addToPlaylist(id, tracks)`	`playlist`	否	向歌单添加歌曲
`updatePlaylistSettings(id, settings)`	`playlist`	否	更新歌单设置
`listPlaylists()`	`playlist`	否	列出所有歌单

⚠️ 标记为「敏感操作」的 API 每次调用都会弹出用户确认窗口，详见安全模型。

本地程序调用

execProgram(path, args)

调用用户本地的可执行文件，传入参数数组。

suchmusic.execProgram(programPath: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }>

参数：

参数	类型	说明
`programPath`	`string`	可执行文件的绝对路径
`args`	`string[]`	命令行参数数组

返回值：

字段	类型	说明
`code`	`number`	退出码，0 表示成功
`stdout`	`string`	标准输出
`stderr`	`string`	标准错误输出

ℹ️ 无论程序执行成功与否，Promise 都会 resolve（不会 reject）。需检查 code 判断执行结果。

示例：

async function checkDecryptor(path: string) {
  const result = await suchmusic.execProgram(path, ['--version'])
  if (result.code === 0) {
    console.log('版本:', result.stdout.trim())
  } else {
    console.error('执行失败:', result.stderr)
  }
}

execTerminal(command)

执行任意终端命令，返回标准输出。执行超时 60 秒。

suchmusic.execTerminal(command: string): Promise<string>

参数：

参数	类型	说明
`command`	`string`	完整的 Shell 命令字符串

返回值： Promise<string> — 标准输出内容。执行失败时 Promise reject。

示例：

async function getFileInfo(filePath: string) {
  try {
    const output = await suchmusic.execTerminal(
      `ffprobe -v quiet -print_format json -show_format "${filePath}"`
    )
    const info = JSON.parse(output)
    console.log('文件信息:', info.format)
  } catch (err) {
    console.error('获取文件信息失败:', err.message)
  }
}

文件操作

fileOp(operation, ...args)

对本地文件系统进行读写操作。

suchmusic.fileOp(operation: string, ...args: string[]): Promise<any>

支持的 operation：

operation	参数	返回值	说明
`read`	`(filePath)`	`string`	读取文件内容（UTF-8）
`write`	`(filePath, content)`	`true`	写入内容到文件
`copy`	`(srcPath, destPath)`	`true`	复制文件
`delete`	`(filePath)`	`true`	删除文件
`exists`	`(filePath)`	`boolean`	文件是否存在
`listDir`	`(dirPath)`	`string[]`	列出目录下的文件名

示例：

async function isAlreadyProcessed(filePath: string) {
  const exists = await suchmusic.fileOp('exists', filePath)
  return exists
}

async function readConfig(configPath: string) {
  const content = await suchmusic.fileOp('read', configPath)
  return JSON.parse(content)
}

async function listMusicFiles(dirPath: string) {
  const files = await suchmusic.fileOp('listDir', dirPath)
  return files.filter(f => f.endsWith('.mp3') || f.endsWith('.flac'))
}

writeMeta(filePath, tags)

写入音乐文件的元数据标签（标题、艺术家、专辑、封面等）。

suchmusic.writeMeta(filePath: string, tags: Record<string, any>): Promise<boolean>

参数：

参数	类型	说明
`filePath`	`string`	音乐文件路径
`tags`	`object`	元数据标签对象

常用 tags 字段：

字段	类型	说明
`title`	`string`	歌曲标题
`artist`	`string`	艺术家
`album`	`string`	专辑名
`cover`	`string \| Buffer`	封面图片（路径或 Buffer）

示例：

async function tagMusicFile(filePath: string) {
  const success = await suchmusic.writeMeta(filePath, {
    title: '歌曲标题',
    artist: '艺术家名称',
    album: '专辑名称'
  })
  if (success) {
    console.log('元数据写入成功')
  }
}

网络请求

fetch(url, options?)

发起 HTTP 请求，与标准 fetch API 行为一致。

suchmusic.fetch(url: string, options?: RequestInit): Promise<Response>

示例：

async function checkServerVersion() {
  const response = await suchmusic.fetch('https://api.example.com/plugin/version')
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`)
  }
  const data = await response.json()
  return data.version
}

async function fetchWithCookie(url: string, cookie: string) {
  const response = await suchmusic.fetch(url, {
    headers: { 'Cookie': cookie }
  })
  return response.json()
}

downloadFile(url, destPath)

下载远程文件并保存到本地路径。需要同时声明 fetch 和 file_system 权限。

suchmusic.downloadFile(url: string, destPath: string): Promise<{ success: boolean; filePath: string }>

参数：

参数	类型	说明
`url`	`string`	文件下载地址
`destPath`	`string`	本地保存路径（包含文件名）

返回值：

字段	类型	说明
`success`	`boolean`	是否下载成功
`filePath`	`string`	保存的文件路径

示例：

async function downloadDecryptor() {
  const musicFolder = suchmusic.getSetting('musicFolder')
  const destPath = musicFolder + '\\ncmdump-go.exe'

  const result = await suchmusic.downloadFile(
    'https://github.com/example/ncmdump-go/releases/latest/download/ncmdump-go.exe',
    destPath
  )

  if (result.success) {
    window.notify('下载完成: ' + result.filePath, 'success')
  }
}

应用设置

getSetting(key)

读取 Such Music 的全局配置。

suchmusic.getSetting(key: string): any

支持的 key：

Key	返回类型	说明
`musicFolder`	`string`	音乐文件夹路径，如 `C:\Users\xxx\Music\Such`
`theme`	`string`	当前主题：`dark` / `light` / `system`

示例：

async function getMusicFolder() {
  const folder = suchmusic.getSetting('musicFolder')
  console.log('音乐文件夹:', folder)
  return folder
}

initialization() {
  const musicFolder = suchmusic.getSetting('musicFolder')
  this.setProps({ musicFolder })
}

⚠️ getSetting 是同步方法，直接返回结果，不需要 await。

歌单操作

createPlaylist(name, tracks?)

创建新的歌单。

suchmusic.createPlaylist(name: string, tracks?: PlaylistTrack[]): Promise<{ id: string; name: string }>

参数：

参数	类型	说明
`name`	`string`	歌单名称
`tracks`	`PlaylistTrack[]`	初始曲目列表（可选）

PlaylistTrack 类型：

interface PlaylistTrack {
  id?: string | number | null
  title: string
  artist: string
  album?: string
  cover?: string
  filePath?: string
  durationMs?: number
  source?: string
  sourceSongId?: string | number
}

示例：

async function importPlaylist(name: string, songList: any[]) {
  const tracks = songList.map(song => ({
    title: song.title,
    artist: song.artist,
    album: song.album,
    cover: song.coverUrl,
    filePath: song.localPath,
    durationMs: song.duration,
    source: 'custom',
    sourceSongId: String(song.id)
  }))

  const result = await suchmusic.createPlaylist(name, tracks)
  window.notify(`歌单 "${name}" 创建成功`, 'success')
  return result
}

addToPlaylist(playlistId, tracks)

向现有歌单添加歌曲。

suchmusic.addToPlaylist(playlistId: string, tracks: PlaylistTrack[]): Promise<any>

updatePlaylistSettings(playlistId, settings)

更新歌单设置（名称、描述等）。

suchmusic.updatePlaylistSettings(playlistId: string, settings: Record<string, any>): Promise<any>

listPlaylists()

列出所有歌单。

suchmusic.listPlaylists(): Promise<Playlist[]>

示例：

async function findPlaylistByName(name: string) {
  const playlists = await suchmusic.listPlaylists()
  return playlists.find(p => p.name === name)
}

suchmusic 宿主 API 参考

On this page