moxxy/custom-xeps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

file-thumbnails: changes

Browse Source
This commit is contained in:
PapaTutuWawa 2022-06-30 12:07:01 +02:00
parent a8d785d80f
commit c7c7f5784a
1 changed files with 45 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
xep-xxxx-file-thumbnails.md
View File

@ -1,4 +1,4 @@
# File Thumbnails # Extensible File Thumbnails
## Introduction ## Introduction
When sending media, it is often helpful for users when a thumbnail can be shown before the When sending media, it is often helpful for users when a thumbnail can be shown before the
@ -9,73 +9,46 @@ However, this protocol requires that the thumbnail is a base64-encoded image pub
[Bits of Binary](https://xmpp.org/extensions/xep-0231.html). This prevents clients from implementing newer technologies, such as [Bits of Binary](https://xmpp.org/extensions/xep-0231.html). This prevents clients from implementing newer technologies, such as
[Blurhash](https://github.com/woltapp/blurhash). [Blurhash](https://github.com/woltapp/blurhash).
This document specifies are more general and extensible element for specifiying thumbnails. This document specifies are more general and extensible element for specifiying thumbnails in various formats.
## Usage ## Usage
```xml ```xml
<file-thumbnail type="blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0"> <file-thumbnails xmlns="proto:urn:xmpp:eft:0">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash> <blurhash xmlns="proto:urn:xmpp:eft:blurhash">LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> </file-thumbnails>
``` ```
In this example, the thumbnail is specified of type `proto:urn:xmpp:file-thumbnails:0:blurhash`, which means that a supporting In this example, the thumbnail contains only a blurhash thumbnail, indicated by the `<blurhash/>` element, but an implementation
client should decode the `<blurhash/>` element using the [Blurhash](https://github.com/woltapp/blurhash) algorithm. may add more versions of the same thumbnail, i.e. another `<base64-bob/>` element as a fallback if a client does not support
blurhash. To prevent confusion in the display of a thumbnail, all children of `<file-thumbnail />` must describe a thumbnail
Other extensions may define similar types. Note that the content of the `<file-thumbnail />` element for the same file.
is dependent on the type specified in the `<file-thumbnail />` element.
### Thumbnail Types ### Thumbnail Types
#### Blurhash #### Blurhash
If a sender specifies the type to be of `blurhash`, then the `<file-thumbnail />` element must contain the If a sender includes a `<blurhash/>` inside the `<file-thumbnail/>` element, then it must be interpreted as
image data as specified by the [Blurhash](https://github.com/woltapp/blurhash) algorithm. Care should be taken to prevent [Blurhash](https://github.com/woltapp/blurhash) data. As a sender, care must be taken to not make the Blurhash
the blurhash data from growing to large in order to prevent hitting the stanza size limit. thumbnail too big as to not loose the advantages of blurhash.
```xml ```xml
<file-thumbail xmlns="proto:urn:xmpp:file-thumbnails:0" type="blurhash"> <file-thumbails xmlns="proto:urn:xmpp:eft:0">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash> <blurhash xmlns="proto:urn:xmpp:eft:blurhash">LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</file-thumbnail> </file-thumbnails>
``` ```
#### Jingle Content Thumbnail Compatability #### Jingle Content Thumbnail Compatability
In order to enable a pseudo-interoperability with [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html), a type In order to enable a pseudo-interoperability with [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html), inclusion of a
`base64-bob` is defined. `<thumbnail/>` element is allowed. This is to allow easy reuse of an already existent [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html)
implementation.
If a sender specified the type to be of `base64-bob`, then the `<file-thumbnail />`
element must contain exactly one `<base64-bob />` element. The attributes of the element are the same
as the `<thumbnail />` element specified in [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html).
```xml ```xml
<file-thumbail xmlns="proto:urn:xmpp:file-thumbnails:0" type="base64-bob"> <file-thumbails xmlns="proto:urn:xmpp:eft:0" type="base64-bob">
<base64-bob uri="cid:sha1+...@bob.xmpp.org" media-type="image/png" width="128" height="96" /> <thumbnail xmlns="urn:xmpp:thumbs:1" uri="cid:sha1+...@bob.xmpp.org" media-type="image/png" width="128" height="96" />
</file-thumbnail> </file-thumbnails>
``` ```
This allows clients that already support [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html) to reuse
the same logic they use for retrieving thumbnail data.
#### Base64 Data
If a sender specified the type to be of `base64`, then the `<file-thumbnail />` element must
contain exactly one `<base64 />` element. The element must posess an `media-type` attribute, whose value
contains the mime type of the thumbnail data, while the inner text of the element contains the base64-encoded
binary thumbnail data.
```xml
<file-thumbail xmlns="proto:urn:xmpp:file-thumbnails:0" type="base64">
<base64 media-type="image/png" width="128" height="96">
[base64 data]
</base64>
</file-thumbnail>
```
Note that this thumbnail type is essentially the same as the `base64-bob` type, but allowing the thumbnail to be used even if
the sender is not available on a server that does not cache [Bits of Binary](https://xmpp.org/extensions/xep-0231.html) data or has it otherwise not available.
If using this thumbnail type, care has to be taken in order to not hit any existing stanza size limits.
## Usage Example with Stateless Inline Media Sharing ## Usage Example with Stateless Inline Media Sharing
NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.org/extensions/xep-0385.html) and modified for this protocol. NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.org/extensions/xep-0385.html) and modified for this protocol.
@ -95,9 +68,14 @@ NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.o
<file-thumbnail type="base64-bob" xmlns='urn:xmpp:thumbnail:0'> <file-thumbnail type="base64-bob" xmlns='urn:xmpp:thumbnail:0'>
<base64-bob uri="cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org" media-type="image/png" width="128" height="96" /> <base64-bob uri="cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org" media-type="image/png" width="128" height="96" />
</thumbnail> </thumbnail>
<file-thumbnail type="blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0"> <file-thumbnails xmlns="proto:urn:xmpp:eft:0">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash> <blurhash xmlns="proto:urn:xmpp:eft:blurhash">LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> <thumbnail xmlns='urn:xmpp:thumbs:1'
uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
media-type='image/png'
width='128'
height='96'/>
</file-thumbnails>
</file> </file>
<sources> <sources>
<reference xmlns='urn:xmpp:reference:0' type='data' uri='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' /> <reference xmlns='urn:xmpp:reference:0' type='data' uri='https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg' />
@ -112,9 +90,24 @@ NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.o
The same considerations apply as specified by [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html). The same considerations apply as specified by [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html).
## Todo
- Change XML namespace from `proto:urn:xmpp:eft:0` to `urn:xmpp:eft:0` once accepted as an experimental XEP
## Changelog
### 0.1.0
- Remove the base64 thumbnail type
- Namespace all thumbnail types
- Remove the type attribute of <file-thumbnail/>
- Rename <file-thumbnail/> to <file-thumbnails/>
- Rename the namespace from file-thumbnails to eft
- Rename from File Thumbnails to Extensible File Thumbnails
## Info ## Info
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| Author | PapaTutuWawa | | Author | PapaTutuWawa |
| Version | 0.0.3 | | Version | 0.1.0 |
| Short name | eft |