Update file-thumbnails

- Remove the namespaced versions of the thumbnail types
- Add the "base64" and "base64-bob" types
This commit is contained in:
PapaTutuWawa 2022-02-28 20:43:30 +01:00
parent 689bd36c8d
commit 606b3aae90

View File

@ -14,7 +14,7 @@ This document specifies are more general and extensible element for specifiying
## Usage ## Usage
```xml ```xml
<file-thumbnail type="proto:urn:xmpp:file-thumbnails:0:blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0"> <file-thumbnail type="blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash> <blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> </thumbnail>
``` ```
@ -22,33 +22,59 @@ This document specifies are more general and extensible element for specifiying
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 is specified of type `proto:urn:xmpp:file-thumbnails:0:blurhash`, which means that a supporting
client should decode the `<blurhash/>` element using the [Blurhash](https://github.com/woltapp/blurhash) algorithm. client should decode the `<blurhash/>` element using the [Blurhash](https://github.com/woltapp/blurhash) algorithm.
In order to enable a sort-of interoperability with [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html), a type
`proto:urn:xmpp:file-thumbnails:0:jct` is defined.
```xml
<file-thumbnail type="proto:urn:xmpp:file-thumbnails:0:jct" xmlns="proto:urn:xmpp:file-thumbnails:0">
<thumbnail xmlns="urn:xmpp:thumbs:1" uri="..." media-type="image/png" width="128" height="96" />
</thumbnail>
```
In the case of [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html) compatibility,
the `<file-thumbnail />` element must contain exactly one `<thumbnail xmlns="urn:xmpp:thumbs:1" />` element.
Other extensions may define similar types. Note that the content of the `<file-thumbnail />` element Other extensions may define similar types. Note that the content of the `<file-thumbnail />` element
is dependent on the type specified in the `<file-thumbnail xmlns="proto:urn:xmpp:file-thumbnails:0" />` is dependent on the type specified in the `<file-thumbnail />` element.
element.
### Thumbnail Types ### Thumbnail Types
#### Blurhash #### Blurhash
If a sender specifies the type to be of `proto:urn:xmpp:file-thumbnails:0:blurhash`, then the `<file-thumbnail />` element must contain the If a sender specifies the type to be of `blurhash`, then the `<file-thumbnail />` element must contain the
image data as specified by the [Blurhash](https://github.com/woltapp/blurhash) algorithm. Care should be taken to prevent image data as specified by the [Blurhash](https://github.com/woltapp/blurhash) algorithm. Care should be taken to prevent
the blurhash data from growing to large in order to prevent hitting the stanza size limit. the blurhash data from growing to large in order to prevent hitting the stanza size limit.
```xml
<file-thumbail xmlns="proto:urn:xmpp:file-thumbnails:0" type="blurhash">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</file-thumbnail>
```
#### Jingle Content Thumbnail Compatability #### Jingle Content Thumbnail Compatability
If a sender specified the type to be of `proto:urn:xmpp:file-thumbnails:0:jct`, then the `<file-thumbnail />` In order to enable a pseudo-interoperability with [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html), a type
element must contain exactly one `<thumbnail xmlns="urn:xmpp:thumbs:1" />` element. `base64-bob` is defined.
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
<file-thumbail xmlns="proto:urn:xmpp:file-thumbnails:0" type="base64-bob">
<base64-bob uri="cid:sha1+...@bob.xmpp.org" media-type="image/png" width="128" height="96" />
</file-thumbnail>
```
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
@ -66,10 +92,10 @@ NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.o
<hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash> <hash xmlns='urn:xmpp:hashes:2' algo='sha3-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>
<hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash> <hash xmlns='urn:xmpp:hashes:2' algo='id-blake2b256'>2AfMGH8O7UNPTvUVAM9aK13mpCY=</hash>
<desc>Photo from the summit.</desc> <desc>Photo from the summit.</desc>
<file-thumbnail type="proto:proto:urn:xmpp:file-thumbnails:0:jct" xmlns='urn:xmpp:thumbnail:0'> <file-thumbnail type="base64-bob" xmlns='urn:xmpp:thumbnail:0'>
<thumbnail xmlns='urn:xmpp:thumbs:1'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="proto:urn:xmpp:file-thumbnails:0:blurhash" xmlns='proto:urn:xmpp:file-thumbnails:0'> <file-thumbnail type="blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0">
<blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash> <blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> </thumbnail>
</file> </file>
@ -91,4 +117,4 @@ The same considerations apply as specified by [Jingle Content Thumbnails](https:
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| Author | PapaTutuWawa | | Author | PapaTutuWawa |
| Version | 0.0.2 | | Version | 0.0.3 |