Playback RPC reference

SDK channel movement and session configurationCopy Anchor Link

The logical guild identity is (clientSessionId, guildId); channelId is a mutable destination. Different bot identities may own the same guild on the same server. The server does not enforce cross-client uniqueness of (botUserId, guildId). Applications must avoid competing controllers for the same bot. Detached resumable sessions retain their ownership and resources until resumption, explicit close, or expiry. No cross-client takeover or transport sharing is performed.

The SDK's move(channelId) uses existing voice.suspend and generation-fenced voice.connect with the new channel and fresh Gateway credentials. It preserves the guild player and playback generation. Movement uses the same protocol-v1 voice commands. Initial gain and filters use the existing player.volume.set and player.filter.set commands before player.play. Configuration persists across tracks and transport generations. Self-deaf and self-mute are Gateway OP 4 fields managed by the application-side SDK, so they add no server wire fields. See the client session configuration guide.

Media probingCopy Anchor Link

After client.create or client.resume, an authenticated connection may send:

{
  "version": 1,
  "id": "probe-1",
  "command": "media.probe",
  "params": {
    "source": { "type": "url", "url": "https://example.com/audio.mp3" },
    "timeoutMs": 15000
  }
}

File sources use {"type":"file","path":"/allowed/audio.mp3"} and resolve on the server. Operation sources are rejected with invalid_request: their media grants are single use, so probing would consume them. Existing URL policy and file-root authorization apply. Bytes and client Readables are unsupported. No guild ID, player or voice transport is involved. The result is the existing AudioStreamInfo object: streamIndex, codec, sampleRate, channels, channelLayout, durationMs, bitRate, and metadata. Unknown numeric fields are null. Missing tags are absent.

timeoutMs is optional, defaults to 15000 and must be an integer from 1 through 4294967295. The configured RPC request timeout also applies. Native work runs on blocking workers, with at most eight simultaneous probes server-wide and no waiting queue. Capacity errors use resource_exhausted. Policy/parameter errors use invalid_request. Native errors use media_failed, cancelled or request_timeout. Sources are closed immediately after inspection and never retained for playback.

To cancel an outstanding probe on the same connection, send media.probe.cancel with {"requestId":"probe-1"}. It returns {"cancelled":true} even if the request already completed. Socket disconnect, request timeout and cancellation interrupt the native operation. Blocking workers retain their capacity permit until native cleanup finishes. FFmpeg discovery can consume source bytes and estimate durations. It does not establish future playback availability.

Staged playback RPCCopy Anchor Link

node.info.capabilities.crossfade reports policy, availability, defaults and the equalPower curve. guild.create accepts optional crossfade: { enabled: true, durationMs: 5000, prepareBeforeMs: 30000, curve: 'equalPower' }. Server policy must allow it. Omitted session options preserve ordinary playback.

player.stage.next accepts guildId, a file, URL or operation source, expectedGeneration, entryId, queueRevision, sourceRevision, and optional expiresAtMs (absolute Unix milliseconds). It returns a stage snapshot with identity, state, bufferedMs, source metadata and nullable error. The client SDK exposes stream metadata as info in its StageSnapshot. player.stage.state returns the current snapshot or null. player.stage.clear cancels the pending stage. player.prepare.ack accepts guildId and expectedGeneration, returning acknowledged and the current generation. Acknowledgment is optional and never delays outgoing playback.

For an operation source, the operation runs before the stage is created and expiresAtMs is ignored, because the node redeems the media immediately. A stage request whose expectedGeneration is already stale fails with stale_generation before any operation runs. A pending preparation is superseded by a newer queueRevision, or a newer sourceRevision for the same entry, and cancelled by player.stage.clear, player.stop, a replacement player.play, guild destruction or shutdown. A result that arrives after the generation changed is discarded with stale_generation.

Notifications are player.prepare_requested, player.stage_ready, player.stage_failed, player.stage_invalidated, and player.transition_cancelled. Preparation includes remainingMs and transitionInMs. Stage events carry queue and source revisions. Incoming player.started includes transition: { type: 'crossfade', outgoingGeneration, entryId }. Outgoing player.completed includes continuation: { type: 'promoted', generation, entryId } after the fade. The final source completes normally. Clients must reconcile the promotion without sending a second player.play.