Reference + Console

## Stage API

Quickstart

### Connection

Stage address Bearer token
1. Enable Stage Mode

在 Folia 设置中开启 Stage Mode，并复制 Bearer token。

2. Pick an endpoint

左侧目录按接口分组，适合先看文档再发请求。

3. Validate with live preview

所有请求都能先看到最终 method、headers 和 body，再真正发送。

Overview

### Endpoint Surface

GET `/stage/health`

Public health check.

GET `/stage/status`

Read active stage state.

POST `/stage/lyrics`

Push parser-compatible lyric source.

POST `/stage/session`

Push media session by URL or file.

POST `/stage/player/search`

Search Netease songs.

POST `/stage/player/play`

Trigger Folia playback.

GET `/stage/player/status`

Read player playback state.

GET `/stage/player/time`

Read precise playback clock.

POST `/stage/player/control`

Send transport controls.

GET `/stage/player/queue`

Read player queue.

POST `/stage/player/queue`

Edit player queue.

WS `/stage/player/ws`

Subscribe to player events.

DELETE `/stage/state`

Clear current stage input.

Endpoint

### GET`/stage/health`

无需鉴权。用于探活，并确认本地 Stage 入口是否可达。

Auth None
Response JSON

#### cURL example

#### Request preview

No request sent yet.

Endpoint

### GET`/stage/status`

读取当前 active entry、lyrics session 和 media session，需要 Bearer token。

Auth Bearer token
Response JSON

#### cURL example

#### Request preview

No request sent yet.

Endpoint

### POST`/stage/lyrics`

推送 parser-compatible 完整歌词对象，相当于进行一次仅有歌词的无音频播放。适合外部歌词工具、爬虫或自定义同步器对接。

Auth Bearer token
Content-Type application/json

#### Body fields

title
  可选，歌曲标题。
artist
  可选，歌手名。
album
  可选，专辑名。
lyricSource
  必填，完整歌词来源对象，`type` 需为 `embedded`、`local`、`navidrome` 或 `netease`。

#### cURL example

#### Interactive request

Title Artist
Album (optional) Lyric source JSON {"type":"local","lrcContent":"[00:00.00]Hello world","tLrcContent":"[00:00.00]你好，世界","formatHint":"lrc"}

No request sent yet.

Endpoint

### POST`/stage/session`

推送媒体会话。支持 `JSON` 和 `multipart/form-data` 两种形式，适合 URL 拉流或本地文件注入。

Auth Bearer token
Transport JSON or multipart

#### Body fields

audioUrl / audioFile
  二选一，必须提供其一。
lyricsText / lyricsFile
  可选，二选一。
lyricsFormat
  可选，`lrc`、`enhanced-lrc`、`vtt`、`yrc` 或自动识别。
coverUrl / coverFile
  可选，封面来源。
title / artist / album
  可选，补充 metadata。

#### JSON example

#### Multipart example

#### Interactive request

Title Artist
Album Cover URL
Audio URL Audio file
Cover file Lyrics file
Lyrics format
上传音频文件时，Folia 会尝试读取内嵌歌词、封面和 metadata。
Lyrics text [00:00.00]Folia demo line one [00:05.00]Folia demo line two

No request sent yet.

Endpoint

### POST`/stage/player/search`

搜索网易云结果，返回歌曲列表。结果可直接触发 `/stage/player/play` 或追加到主播放器队列。

Auth Bearer token
Content-Type application/json

#### Body fields

query
  必填，歌曲 / 歌手 / 专辑关键词。
limit
  可选，结果数量上限。

#### cURL example

#### Interactive request

Query Limit

No request sent yet.

Endpoint

### POST`/stage/player/play`

从外部触发 Folia 主播放器点歌。在 /stage/player/search 返回的搜索结果中进行调试

Auth Bearer token
Trigger Search result action

#### Body fields

songId
  必填，正整数歌曲 ID。
appendToQueue
  可选，`true` 时只追加到主播放队列，不打断当前播放。（注：Folia 存在自动去重机制，同一歌曲不会在队列中出现两次，若已在队列中则会被移动到目标位置，并通过返回值的 `deduplicated` 字段体现。）

#### cURL example

#### Live request preview

点击搜索结果中的 `Play In Folia` 或 `Add To Queue` 后，这里会显示实际发送的 `/stage/player/play` 请求。

    Search results can be played directly back into Folia.

No request sent yet.

Endpoint

### GET`/stage/player/status`

读取 Folia 播放器域状态，包含当前曲目、播放上下文、控制能力和队列摘要。不会返回完整队列 items。

Auth Bearer token
Response JSON

#### cURL example

#### Request preview

No request sent yet.

Endpoint

### GET`/stage/player/time`

主动校准播放时间。播放中会按主进程收到的快照采样时间推算当前 `positionMs`。

Auth Bearer token
Response Clock JSON

#### cURL example

#### Request preview

No request sent yet.

Endpoint

### POST`/stage/player/control`

发送播放器控制指令。当前上下文不支持时返回 `409 STAGE_PLAYER_CONTROL_UNSUPPORTED`。

Auth Bearer token
Content-Type application/json

#### Body fields

action
  `next`、`prev`、`pause`、`resume` 或 `seek`。
positionMs
  `seek` 时必填，非负整数，无效值会返回 `400`。

#### cURL example

#### Interactive request

Action
Position ms

No request sent yet.

Endpoint

### GET POST`/stage/player/queue`

读取或编辑正常播放器队列。GET 默认返回 100 条队列窗口，支持 offset、limit 和 around=current。

Auth Bearer token
Content-Type application/json for POST

#### POST action

append / insert-next
  需要 `songId` 或 `songIds`。（注：Folia 会对歌曲自动去重，若歌曲已在队列中则会被直接移动到目标位置，不会重复添加；请求本身如果有重复歌曲也会被合并。响应的 `deduplicated` 字段会体现去重状态。）
remove / select
  需要 `queueItemId` 或 `index`，`select` 会切到该队列项播放。使用 `queueItemId` 时会严格校验项匹配度。
move
  需要 `fromQueueItemId` 或 `fromIndex`，并提供 `toIndex`。使用 `queueItemId` 时会严格校验项匹配度。
clear
  清空队列中非当前播放项。

#### cURL example

#### Interactive request

Action
Song ID
Queue item ID From queue item ID
Index To index
GET offset GET limit
Center GET window around current track

No request sent yet.

Endpoint

### WS`/stage/player/ws`

订阅播放器事件。TRACK_CHANGED 不携带 positionMs / durationMs；PLAYBACK_UPDATED 只推送播放时间和状态。

Auth Bearer token or ?token=
Transport WebSocket

#### URL preview

#### Event log

Disconnected.

    No events yet.

Endpoint

### DELETE`/stage/state`

清空当前 Stage 输入，不区分 lyrics 或 media，会把当前注入态整体移除。

Auth Bearer token
Effect Clear stage state

#### cURL example

#### Request preview

No request sent yet.