Entrance sounds¶

An entrance sound is a short audio clip an account plays while it is connected to a voice channel. An account uploads a clip once into its own library, assigns it to a scope, and plays it for the other participants of a voice channel. Voice describes where the feature sits.

Every route on this page is user-only, requires no channel permission, and acts on the caller's own library. A bot token is rejected with 403 ACCESS_DENIED.

Clip limits¶

Supported containers¶

TEBHOS detects the container from the decoded bytes, so a filename, a data: media type, or any other declared type has no effect. The duration is read from the container itself, and a file whose duration cannot be read is rejected.

Every other format, including FLAC, WebM, Matroska, and AIFF, is rejected.

The decoded bytes are stored exactly as they arrived, under the extension and content type the table assigns.

Entrance sound object¶

One stored audio clip owned by one account. Every field except name is fixed at upload.

Structure¶

Example¶

{
  "id": "1501314428688998182",
  "name": "airhorn",
  "hash": "9f2c41ab77de0135",
  "extension": "mp3",
  "content_type": "audio/mpeg",
  "duration_ms": 1240,
  "size_bytes": 20416,
  "url": "https://cdn.tebhos.com/entrance-sounds/1490000000000000000/9f2c41ab77de0135.mp3",
  "created_at": "2026-09-20T09:12:04.118+00:00"
}

Entrance sound selection object¶

One scope and the clip assigned to it.

Structure¶

A scope with no assigned sound has no selection object.

Example¶

{
  "scope_id": "guild:1490000000000000123",
  "sound_id": "1501314428688998182"
}

Entrance sound scopes¶

The TEBHOS clients use these scope values:

TEBHOS stores scope_id as sent and does not validate its format, so use one of these values. Scopes are only a client-side convention: Play entrance sound names the clip explicitly, and the client decides which selection applies to a channel.

List entrance sounds¶

GET /users/@me/entrance-sounds

Returns the current account's complete entrance sound library together with its per-scope selections.

Response body¶

Both members are always present, and both arrays are empty for an account that has uploaded nothing.

Rate limit¶

30 requests per minute for each user, on the user:entrance_sound:list bucket.

Upload entrance sound¶

POST /users/@me/entrance-sounds

Decodes, validates, and stores one audio clip in the current account's library, and returns 201 with the created entrance sound object.

JSON body¶

Validation¶

Every failure below returns 400 INVALID_FORM_BODY with a human-readable message. The checks run in this order.

A request body larger than the upload limit (about 1.4 MiB of base64 plus 64 KiB) is rejected before validation.

Response¶

Side effects¶

The operation assigns no scope and emits no Gateway Dispatch. Uploading the same bytes twice creates two library entries with the same hash and url. Deleting one leaves the other usable.

Rate limit¶

5 requests per 5 minutes for each user, on the user:entrance_sound:upload bucket.

Rename entrance sound¶

PATCH /users/@me/entrance-sounds/{sound_id}

Changes the display label of one clip and returns the updated entrance sound object.

Path parameters¶

JSON body¶

Response¶

A clip owned by another account is reported exactly like one that never existed.

Side effects¶

Only the label changes. Selections pointing at the clip keep pointing at it. No Gateway Dispatch is emitted.

Rate limit¶

20 requests per minute for each user, on the user:entrance_sound:mutate bucket, shared with Delete entrance sound and Set entrance sound selection.

Delete entrance sound¶

DELETE /users/@me/entrance-sounds/{sound_id}

Deletes one clip from the current account's library, clears every selection that pointed at it, and returns 204 with an empty body. An unknown clip, or a clip owned by another account, is a successful no-op.

Path parameters¶

Response¶

Side effects¶

The clip and every selection naming it are removed. The stored audio file is removed too, unless another clip in the library has the same content. No Gateway Dispatch is emitted.

Rate limit¶

20 requests per minute for each user, on the shared user:entrance_sound:mutate bucket.

Set entrance sound selection¶

PUT /users/@me/entrance-sound-selections

Assigns a clip to one scope, or clears that scope, and returns 204 with an empty body. A scope that already has a sound is overwritten. Requires TEBHOS Pro.

JSON body¶

TEBHOS does not check that sound_id names a clip in the caller's library. A client SHOULD send only IDs returned by List entrance sounds.

Response¶

Side effects¶

One clip can be selected in any number of scopes. No Gateway Dispatch is emitted, so the caller's other sessions learn about the change only by listing the library again.

Rate limit¶

20 requests per minute for each user, on the shared user:entrance_sound:mutate bucket.

Play entrance sound¶

POST /voice/channels/{channel_id}/entrance-sound

Tells every other account connected to a voice channel to play the caller's clip, and returns 204 with an empty body. The caller must hold a voice connection in that channel and must own the clip. Requires TEBHOS Pro. Emits ENTRANCE_SOUND_PLAY.

Recipients fetch and play the clip locally from the URL in the event.

Path parameters¶

JSON body¶

Response¶

Side effects¶

TEBHOS sends one ENTRANCE_SOUND_PLAY Dispatch to every other account holding a voice state in the channel, at most once for each account, and never to the caller. The Dispatch is addressed to the account, so every session that account holds receives it, including sessions that are not in the channel. A client filters on channel_id.

Rate limit¶

3 requests per 30 seconds for each user and channel, on the voice:entrance_sound:play bucket.