Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document voice messages. #6082

Merged
merged 3 commits into from
Apr 19, 2023
Merged

Document voice messages. #6082

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d977002
Document voice messages.
tpcstld Apr 14, 2023
c287228
Updates.
tpcstld Apr 14, 2023
2602706
More updates.
tpcstld Apr 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
41 changes: 29 additions & 12 deletions docs/resources/Channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,7 @@ Represents a message sent in a channel within Discord.
| LOADING | 1 << 7 | this message is an Interaction Response and the bot is "thinking" |
| FAILED_TO_MENTION_SOME_ROLES_IN_THREAD | 1 << 8 | this message failed to mention some roles and add their members to the thread |
| SUPPRESS_NOTIFICATIONS | 1 << 12 | this message will not trigger push and desktop notifications |
| IS_VOICE_MESSAGE | 1 << 13 | this message is a voice message |

###### Example Message

Expand Down Expand Up @@ -512,6 +513,20 @@ There are multiple message types that have a message_reference object. Since me
- These messages have `message_id`, `channel_id`, and `guild_id`.
- These messages will never have content, embeds, or attachments, mainly just the `message_reference` and `referenced_message` fields.

#### Voice Messages

Voice messages are messages with the `IS_VOICE_MESSAGE` flag. They have the following properties.

- They cannot be edited.
- Only a single audio attachment is allowed. No content, stickers, etc...
- The [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) has additional fields: `duration_secs` and `waveform`.

The `waveform` is intended to be a preview of the entire voice message, with 1 byte per datapoint encoded in base64. Clients sample the recording at most
once per 100 milliseconds, but will downsample so that no more than 256 datapoints are in the waveform.

As of 2023-04-14, clients upload a 1 channel, 48000 Hz, 32kbps Opus stream in an OGG container.
The encoding, and the waveform details, are an implementation detail and may change without warning or documentation.

### Followed Channel Object

###### Followed Channel Structure
Expand Down Expand Up @@ -729,18 +744,20 @@ Embeds are deduplicated by URL. If a message contains multiple embeds with the
> info
> For the `attachments` array in Message Create/Edit requests, only the `id` is required.

| Field | Type | Description |
| ------------- | --------- | ----------------------------------------------------------------------- |
| id | snowflake | attachment id |
| filename | string | name of file attached |
| description? | string | description for the file (max 1024 characters) |
| content_type? | string | the attachment's [media type](https://en.wikipedia.org/wiki/Media_type) |
| size | integer | size of file in bytes |
| url | string | source url of file |
| proxy_url | string | a proxied url of file |
| height? | ?integer | height of file (if image) |
| width? | ?integer | width of file (if image) |
| ephemeral? \* | boolean | whether this attachment is ephemeral |
| Field | Type | Description |
| -------------- | --------- | --------------------------------------------------------------------------------------- |
| id | snowflake | attachment id |
| filename | string | name of file attached |
| description? | string | description for the file (max 1024 characters) |
| content_type? | string | the attachment's [media type](https://en.wikipedia.org/wiki/Media_type) |
| size | integer | size of file in bytes |
| url | string | source url of file |
| proxy_url | string | a proxied url of file |
| height? | ?integer | height of file (if image) |
| width? | ?integer | width of file (if image) |
| ephemeral? \* | boolean | whether this attachment is ephemeral |
| duration_secs? | float | the duration of the audio file (currently for voice messages) |
| waveform? | string | base64 encoded bytearray representing a sampled waveform (currently for voice messages) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be worthwhile to document the exact format of this data? Apparently it's 8bit 10Hz


\* Ephemeral attachments will automatically be removed after a set period of time. Ephemeral attachments on messages are guaranteed to be available as long as the message itself exists.

Expand Down
5 changes: 5 additions & 0 deletions docs/topics/Opcodes_and_Status_Codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,11 @@ Along with the HTTP error code, our API can also return more detailed error code
| 50145 | Cannot convert between premium emoji and normal emoji |
| 50146 | Uploaded file not found. |
| 50163 | Cannot delete guild subscription integration |
| 50159 | Voice messages do not support additional content. |
| 50160 | Voice messages must have a single audio attachment. |
| 50161 | Voice messages must have supporting metadata. |
| 50162 | Voice messages cannot be edited. |
| 50173 | You cannot send voice messages in this channel. |
| 50600 | You do not have permission to send this sticker. |
| 60003 | Two factor is required for this operation |
| 80004 | No users with DiscordTag exist |
Expand Down
1 change: 1 addition & 0 deletions docs/topics/Permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ Below is a table of all current permissions, their integer values in hexadecimal
| MODERATE_MEMBERS \*\* | `0x0000010000000000` `(1 << 40)` | Allows for timing out users to prevent them from sending or reacting to messages in chat and threads, and from speaking in voice and stage channels | |
| VIEW_CREATOR_MONETIZATION_ANALYTICS \* | `0x0000020000000000` `(1 << 41)` | Allows for viewing role subscription insights | |
| USE_SOUNDBOARD | `0x0000040000000000` `(1 << 42)` | Allows for using soundboard in a voice channel | V |
| SEND_VOICE_MESSAGES | `0x0000400000000000` `(1 << 46)` | Allows sending voice messages | T, V, S |

**\* These permissions require the owner account to use [two-factor authentication](#DOCS_TOPICS_OAUTH2/twofactor-authentication-requirement) when used on a guild that has server-wide 2FA enabled.**

Expand Down