Update "File Thumbnails"

- Rename from "Thumbnails" to prevent a XML tag clash with Jingle
  Content Thumbnails
- Prepend a "proto:" to the chosen xmlns to prevent issues with live
  XEPs
- Add information about this not-really-proto XEP
This commit is contained in:
PapaTutuWawa 2022-02-27 18:56:08 +01:00
parent bbaa932ec8
commit 6d9e295741

View File

@ -1,4 +1,4 @@
# Thumbnails # 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
@ -14,42 +14,43 @@ This document specifies are more general and extensible element for specifiying
## Usage ## Usage
```xml ```xml
<thumbnail type="blurhash" xmlns="urn:xmpp:thumbnail:0"> <file-thumbnail type="proto:urn:xmpp:file-thumbnails:0:blurhash" xmlns="proto:urn:xmpp:file-thumbnails:0">
<payload>LEHV6nWB2yk8pyoJadR*.7kCMdnj</payload> <blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> </thumbnail>
``` ```
In this example, the thumbnail is specified of type `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 `<payload/>` 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 In order to enable a sort-of interoperability with [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html), a type
`urn:xmpp:thumbs:0` is defined. If this is specified, then a supporting client must `proto:urn:xmpp:file-thumbnails:0:jct` is defined.
interpret the child of the `<payload />` as an `<thumbnail />` element as specified by
:[Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html)
``` ```xml
<thumbnail type="urn:xmpp:thumbs:1" xmlns="urn:xmpp:thumbnail:0"> <file-thumbnail type="proto:urn:xmpp:file-thumbnails:0:jct" xmlns="proto:urn:xmpp:file-thumbnails:0">
<payload> <thumbnail xmlns="urn:xmpp:thumbs:1" uri="..." media-type="image/png" width="128" height="96" />
<thumbnail xmlns="urn:xmpp:thumbs:1" uri="..." media-type="image/png" width="128" height="96" />
</payload>
</thumbnail> </thumbnail>
``` ```
In the case of [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html) compatibility, In the case of [Jingle Content Thumbnails](https://xmpp.org/extensions/xep-0264.html) compatibility,
the `<payload />` element must contain exactly one `<thumbnail xmlns="urn:xmpp:thumbs:1" />` element. 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 `<payload />` element Other extensions may define similar types. Note that the content of the `<file-thumbnail />` element
is dependent on the type specified in the `<thumbnail xmlns="urn:xmpp:thumbnail:0" />` is dependent on the type specified in the `<file-thumbnail xmlns="proto:urn:xmpp:file-thumbnails:0" />`
element. element.
### Thumbnail Types ### Thumbnail Types
#### Blurhash #### Blurhash
If a sender specifies the type to be of `blurhash`, then the payload must contain the If a sender specifies the type to be of `proto:urn:xmpp:file-thumbnails:0: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.
## Usage with Stateless Inline Media Sharing ### Jingle Content Thumbnail Compatability
If a sender specified the type to be of `proto:urn:xmpp:file-thumbnails:0:jct`, then the `<file-thumbnail />`
element must contain exactly one `<thumbnail xmlns="urn:xmpp:thumbs:1" />` element.
## 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.
@ -65,13 +66,13 @@ 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>
<thumbnail type="urn:xmpp:thumbs:1" xmlns='urn:xmpp:thumbnail:0'> <file-thumbnail type="proto:proto:urn:xmpp:file-thumbnails:0:jct" xmlns='urn:xmpp:thumbnail:0'>
<payload> <payload>
<thumbnail xmlns='urn:xmpp:thumbs:1'uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/> <thumbnail xmlns='urn:xmpp:thumbs:1'uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png' width='128' height='96'/>
</payload> </payload>
</thumbnail> </thumbnail>
<thumbnail type="blurhash" xmlns='urn:xmpp:thumbnail:0'> <file-thumbnail type="proto:urn:xmpp:file-thumbnails:0:blurhash" xmlns='proto:urn:xmpp:file-thumbnails:0'>
<payload>LEHV6nWB2yk8pyoJadR*.7kCMdnj</payload> <blurhash>LEHV6nWB2yk8pyoJadR*.7kCMdnj</blurhash>
</thumbnail> </thumbnail>
</file> </file>
<sources> <sources>
@ -86,3 +87,10 @@ NOTE: This example is taken from [Stateless Inline Media Sharing](https://xmpp.o
## Security Considerations ## Security Considerations
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).
## Info
| Key | Value |
| --- | --- |
| Author | PapaTutuWawa |
| Version | 0.0.2 |