versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2026-03-13 19:09:16 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Create initial docs

Browse source
This commit is contained in:
Jesse Wierzbinski 2023-11-25 13:35:25 -10:00
commit a3576b7458
No known key found for this signature in database
11 changed files with 438 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

104
structures/content-format.md Normal file
View file

@ -0,0 +1,104 @@
# ContentFormat
A `ContentFormat` structure can be represented as such in TypeScript:
```ts
interface ContentFormat {
content: string;
content_type: string;
description?: string;
size?: number;
hash?: {
md5?: string;
sha1?: string;
sha256?: string;
sha512?: string;
[key: string]: string | undefined;
};
blurhash?: string;
fps?: number;
width?: number;
height?: number;
duration?: number;
}
```
An example value would be:
```json
{
"content": "Hello, world!",
"content_type": "text/plain"
}
```
Another example:
```json
{
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.png",
"content_type": "image/png",
"description": "A jolly horse running in the mountains",
"size": 123456,
"hash": {
"sha256": "91714fc336210d459d4f9d9233de663be2b87ffe923f1cfd76ece9d06f7c965d"
}
}
```
The `contents` field is a string that contains the actual content of the object. The `content_type` field is a string that contains the MIME type of the content.
The `content` and `content_type` fields are required on all `ContentFormat` objects, but other fields are optional.
The `description` field is a string that contains a description of the content. It is used to describe the content to users that cannot see the content, such as users that are blind, or when the content does not load properly. It is not required on all `ContentFormat` objects. If it is not provided, it is assumed that the content does not have a description.
The `size` field is a number that contains the size of the content in bytes. It is not required on all `ContentFormat` objects. If it is not provided, it is assumed that the content size is not specified.
It is generally not needed to provide content size for text content, but it is recommended to provide content size for binary content, such as images, videos, and audio. This is useful for clients to determine if they should download the content or not.
It is expected that files in an array of `ContentFormat` objects (when used to store URLs to files) are the same file, but in different formats. For example, a PNG image and a WebP image. Files in formats such as PDF that cannot be converted to other formats should only be stored once.
For example, this is acceptable:
```json
[
{
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.png",
"content_type": "image/png",
"description": "A jolly horse running in the mountains",
"hash": {
"sha256": "91714fc336210d459d4f9d9233de663be2b87ffe923f1cfd76ece9d06f7c965d"
}
},
{
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.webp",
"content_type": "image/webp",
"description": "A jolly horse running in the mountains",
"hash": {
"sha256": "b493d48364afe44d11c0165cf470a4164d1e2609911ef998be868d46ade3de4e"
},
}
]
```
But this is not:
```json
[
{
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.png",
"content_type": "image/png",
"description": "A jolly horse running in the mountains"
},
{
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.webp",
"content_type": "image/webp",
"description": "A jolly horse running in the mountains",
},
{
"content": "https://cdn.example.com/attachments/anotherfile.pdf",
"content_type": "application/pdf",
"description": "A PDF file about macroeconomics"
}
]
```
Each array of ContentFormat objects should be considered as a SINGLE FILE, and not multiple files. The multiple formats are only meant to save bandwidth.
If optional fields are provided on one object in the array, they should be provided on all objects in the array. For example, if the `description` field is provided on one object, it should be provided on all objects (since they are the same file).

55
structures/custom-emoji.md Normal file
View file

@ -0,0 +1,55 @@
# Custom Emojis
Lysand supports custom emojis. They are represented as such in TypeScript:
```ts
interface Emoji {
name: string;
alt?: string;
url: ContentFormat[];
}
```
Lysand custom emojis are implemented as part of an official optional extension to the protocol. See [Protocol Extensions](#protocol-extensions) for more information.
Servers **MAY** choose not to implement custom emojis, but it is recommended that they do so.
An example value would be:
```json
{
"name": "happy_face",
"alt": "A happy face emoji.",
"url": [
{
"content": "https://cdn.example.com/emojis/happy_face.webp",
"content_type": "image/webp"
}
]
}
```
The `name` field **MUST** be a string that contains only alphanumeric characters, underscores, and dashes. It **MUST NOT** contain any spaces or other special characters.
It **MUST** match this regex: `/^[a-zA-Z0-9_-]+$/`
---
The `url` field is an array that contains a list of `ContentFormat` objects. It is meant to serve as a list of URLs that the emoji can be accessed at. It is required on all emojis, and **MUST** contain at least one URL.
The `url` field **MUST** be a binary image format, such as `image/png` or `image/jpeg`. The `url` field **MUST NOT** be a text format, such as `text/plain` or `text/html`.
---
The `alt` field is a string that contains the alt text for the emoji. It is used to describe the emoji to users that cannot see the emoji, such as users that are blind, or when the emoji does not load properly.
The `alt` field is not required on all emojis. If it is not provided, it is assumed that the emoji does not have an alt text.
---
Emojis normally do not need to be transcoded into more modern formats, as they are typically small and do not take up much bandwidth. However, servers **MAY** choose to transcode emojis into more modern formats, such as WebP, AVIF, JXL, or HEIF.
Clients should display the most modern format that they support, such as WebP, AVIF, JXL, or HEIF. If the client does not support any modern formats, it should display the original format.
> **Note:** Servers may find it useful to use a CDN that can automatically convert images to modern formats, such as Cloudflare. This will offload image processing from the server, and improve performance for clients.
Emoji size is not standardized, and is up to the server to decide. Servers **MAY** choose to limit the size of emojis, but it is not required. Generally, an upper limit of a few hundred kilobytes is recommended so as to not take up too much bandwidth.