From bf5ae504434cb8a1317ceeb6421a3789735ecd86 Mon Sep 17 00:00:00 2001 From: Alecks Gates Date: Thu, 6 Jul 2023 01:42:25 -0500 Subject: [PATCH] Podcast RSS Documentation --- .../content/technical/thirdparty/_index.en.md | 97 ++++++++++++++++++- 1 file changed, 95 insertions(+), 2 deletions(-) diff --git a/support/documentation/content/technical/thirdparty/_index.en.md b/support/documentation/content/technical/thirdparty/_index.en.md index 5c35cd2b..2b6bcc09 100644 --- a/support/documentation/content/technical/thirdparty/_index.en.md +++ b/support/documentation/content/technical/thirdparty/_index.en.md @@ -141,7 +141,7 @@ If you want to display the chat in a web page or in an iframe, here is what you * get the Video ActivityPub object, * if there is no `attachment` key, stop. -* loop through the `attachment` values (if `attachment is not an array, just iterate on this single value) +* loop through the `attachment` values (if `attachment` is not an array, just iterate on this single value) * search for an entry with `rel` === `discussion`, and with `href` using the `https` scheme (that begins with `https://`) * if found, open this href @@ -149,7 +149,7 @@ If you want to open the chat room using the XMPP protocol: * get the Video ActivityPub object, * if there is no `attachment` key, stop. -* loop through the `attachment` values (if `attachment is not an array, just iterate on this single value) +* loop through the `attachment` values (if `attachment` is not an array, just iterate on this single value) * search for an entry with `rel` === `discussion`, and with `href` using the `xmpp` scheme (that begins with `xmpp://`) * if found, open this xmpp uri with your client, or connect to the XMPP room at that address @@ -161,6 +161,8 @@ It is currently required for some endpoint discovery. ### Using Podcast RSS feed +The livechat plugin adds some data in Podcast RSS feeds under the [``](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#live-item), so that the chat can be discovered for live streams. + {{% notice warning %}} This part is not implemented yet, but should be available for v7.2.0 release. {{% /notice %}} @@ -168,3 +170,94 @@ This part is not implemented yet, but should be available for v7.2.0 release. {{% notice info %}} This requires Peertube >= 5.2 {{% /notice %}} + +{{% notice info %}} +The `` element is currently only supported for live streams. +{{% /notice %}} + +This follows the [``](https://github.com/Podcastindex-org/podcast-namespace/discussions/502) proposal. + +{{% notice warning %}} +At the time of the writing, this proposal is in draft status, and the livechat plugin is a Proof-of-concept. +Until the proposal is adopted, the specification can change, and the livechat plugin will be adapted accordingly. +{{% /notice %}} + +Basically, the chat will be declared as tag under on the `` element. + +By default, here is an example of what you will get: + +```xml + + The video title + e32b4890-983b-4ce5-8b46-f2d6bc1d8819_2023-07-06T18:00:00.000Z + https://yourinstance.tld/videos/watch/8df24108-6e70-4fc8-b1cc-f2db7fcdd535 + + + + + + + + +``` + +In case the instance has activated the + [external XMPP clients connection](/peertube-plugin-livechat/documentation/admin/advanced/xmpp_clients/) feature: + +```xml + + The video title + e32b4890-983b-4ce5-8b46-f2d6bc1d8819_2023-07-06T18:00:00.000Z + https://yourinstance.tld/videos/watch/8df24108-6e70-4fc8-b1cc-f2db7fcdd535 + + + + + + + + +``` + +#### Algorithm + +If you want to display the chat in a web page or in an iframe, here is what you should do: + +* get the Podcast RSS feed for the channel, +* if there is no `` element under the ``, stop. +* find the `` you are looking for + * `` can be used to cross-reference the items with ActivityPub +* if there is no `` element under the ``, stop. +* loop through the `` values (if `` is not an array, just iterate on this single value) + * there should only be one, but you should expect to handle several just in case +* search for the first entry `protocol` === `xmpp` and an `embedUrl` attribute +* if found, open this embedUrl + +If you want to open the chat room using the XMPP protocol: + +* get the Podcast RSS feed for the channel, +* if there is no `` element under the ``, stop. +* find the `` you are looking for + * `` can be used to cross-reference the items with ActivityPub +* loop through the `` values (if `` is not an array, just iterate on this single value) + * there should only be one, but you should expect to handle several just in case +* search for the first entry `protocol` === `xmpp` and a `space` attribute + * space should be an XMPP JID for a MUC +* if found, open this XMPP JID with your client after converting it to a join URI, or connect to the XMPP room at that address