youtube#

Description#

YouTube plugin.

Unlike other Google plugins, this plugin doesn’t rely on the Google API.

That’s because the official YouTube API has been subject to many changes to prevent scraping, and it requires the user to tinker with the OAuth layer, app permissions and app validation in order to get it working.

Instead, it relies on a Piped, an open-source alternative YouTube gateway.

It thus requires a link to a valid Piped instance.

Configuration#

youtube:
  # [Optional]
  # Base API URL of the Piped instance (default:
  # ``https://pipedapi.kavin.rocks``).
  # piped_api_url: https://pipedapi.kavin.rocks  # type=str

  # [Optional]
  # Optional authentication token from the Piped
  # instance. This is required if you want to access your private feed
  # and playlists, but not for searching public videos.
  #
  # In order to retrieve an authentication token:
  #
  #   1. Login to your configured Piped instance.
  #   2. Copy the RSS/Atom feed URL on the _Feed_ tab.
  #   3. Copy the ``auth_token`` query parameter from the URL.
  #   4. Enter it in the ``auth_token`` field in the ``youtube`` section
  #      of the configuration file.
  # auth_token:   # type=Optional[str]

Dependencies#

pip

pip install yt-dlp

Alpine

apk add yt-dlp

Debian

apt install yt-dlp

Fedora

yum install yt-dlp

Arch Linux

pacman -S yt-dlp

Actions#

Module reference#

class platypush.plugins.youtube.YoutubePlugin(piped_api_url: str = 'https://pipedapi.kavin.rocks', auth_token: str | None = None, **kwargs)[source]#

Bases: Plugin

YouTube plugin.

Unlike other Google plugins, this plugin doesn’t rely on the Google API.

That’s because the official YouTube API has been subject to many changes to prevent scraping, and it requires the user to tinker with the OAuth layer, app permissions and app validation in order to get it working.

Instead, it relies on a Piped, an open-source alternative YouTube gateway.

It thus requires a link to a valid Piped instance.

__init__(piped_api_url: str = 'https://pipedapi.kavin.rocks', auth_token: str | None = None, **kwargs)[source]#
Parameters:
  • piped_api_url – Base API URL of the Piped instance (default: https://pipedapi.kavin.rocks).

  • auth_token

    Optional authentication token from the Piped instance. This is required if you want to access your private feed and playlists, but not for searching public videos.

    In order to retrieve an authentication token:

    1. Login to your configured Piped instance.

    2. Copy the RSS/Atom feed URL on the _Feed_ tab.

    3. Copy the auth_token query parameter from the URL.

    4. Enter it in the auth_token field in the youtube section of the configuration file.

get_channel(id: str, next_page_token: str | None = None) dict[source]#

Retrieve the information and videos of a channel given its ID or URL.

Parameters:
  • id – Channel ID or URL.

  • next_page_token – Optional token to retrieve the next page of results.

Returns:

{
  "banner": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
  "description": "My channel description",
  "id": "1234567890",
  "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
  "items": [
    {
      "channel": "My Channel",
      "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
      "channel_url": "https://youtube.com/channel/1234567890",
      "created_at": "2020-01-01T00:00:00",
      "description": "My video description",
      "duration": 120,
      "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
      "title": "My Video Title",
      "url": "https://youtube.com/watch?v=1234567890"
    }
  ],
  "name": "My Channel Name",
  "next_page_token": "1234567890",
  "subscribers": 1000,
  "url": "https://youtube.com/channel/1234567890"
}

get_feed() List[dict][source]#

Retrieve the YouTube feed.

Depending on your account settings on the configured Piped instance, this may return either the latest videos uploaded by your subscribed channels, or the trending videos in the configured area.

Returns:

[
  {
    "channel": "My Channel",
    "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "channel_url": "https://youtube.com/channel/1234567890",
    "created_at": "2020-01-01T00:00:00",
    "description": "My video description",
    "duration": 120,
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]

get_playlist(id: str) List[dict][source]#

Retrieve the videos in a playlist.

Parameters:

id – Piped playlist ID.

Returns:

[
  {
    "channel": "My Channel",
    "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "channel_url": "https://youtube.com/channel/1234567890",
    "created_at": "2020-01-01T00:00:00",
    "description": "My video description",
    "duration": 120,
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]

get_playlists() List[dict][source]#

Retrieve the playlists saved by the user logged in to the Piped instance.

Returns:

[
  {
    "description": "My video description",
    "id": "12345678-1234-1234-1234-1234567890ab",
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "name": "My Playlist Name",
    "videos": 10
  }
]

get_subscriptions() List[dict][source]#

Retrieve the channels subscribed by the user logged in to the Piped instance.

Returns:

[
  {
    "banner": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "description": "My channel description",
    "id": "1234567890",
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "items": [
      {
        "channel": "My Channel",
        "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
        "channel_url": "https://youtube.com/channel/1234567890",
        "created_at": "2020-01-01T00:00:00",
        "description": "My video description",
        "duration": 120,
        "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
        "title": "My Video Title",
        "url": "https://youtube.com/watch?v=1234567890"
      }
    ],
    "name": "My Channel Name",
    "next_page_token": "1234567890",
    "subscribers": 1000,
    "url": "https://youtube.com/channel/1234567890"
  }
]

search(query: str, **_) List[dict][source]#

Search for YouTube videos.

Parameters:

query – Query string.

Returns:

[
  {
    "channel": "My Channel",
    "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "channel_url": "https://youtube.com/channel/1234567890",
    "created_at": "2020-01-01T00:00:00",
    "description": "My video description",
    "duration": 120,
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]