youtube

youtube#

Description#

YouTube plugin.

This plugin supports multiple backends to interact with YouTube:

  • piped: Uses a Piped instance.

  • invidious: Uses an Invidious

    instance.

  • google: Uses the official Google YouTube API.

You can specify the backend configuration in the plugin configuration through the backends parameter:

youtube:
    backends:
        # For Piped
        piped:
            instance_url: https://pipedapi.kavin.rocks
            auth_token: <auth_token>
            frontend_url: https://piped.kavin.rocks

        # For Invidious
        invidious:
            instance_url: https://yewtu.be
            auth_token: <auth_token>

        # For the official YouTube API
        google:
            # OAuth authentication will be performed through the Google plugin
            # the first time you run the plugin.

Piped#

Warning

At the time of writing (February 2025), the Piped backend isn’t actively tested. That’s because most of the instances seem to be either down or blocked by Google. invidious is the recommended backend.

Parameters:

  • instance_url: Base URL of the Piped instance (default: https://pipedapi.kavin.rocks). NOTE: This should be the URL of the Piped API, not the Piped instance/frontend itself.

  • 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.

  • frontend_url: Optional URL of the Piped frontend. This is needed to generate channels and playlists URLs. If not provided, the plugin will try and infer it by stripping the api string from instance_url.

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.

Invidious#

Parameters:

  • instance_url: Base URL of the Invidious instance (default: https://yewtu.be).

  • auth_token: Optional authentication token from the Invidious 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 Invidious instance.

  2. Open the URL https://<instance_url>/authorize_token?scopes=:* in your browser. Replace <instance_url> with the URL of your Invidious instance, and :* with the scopes you want to assign to the token (although an all-access token is recommended for full functionality).

  3. Copy the generated token.

If both are provided, the Invidious backend will be used.

If none is provided, the plugin will fallback to the default Invidious instance (https://yewtu.be), but authenticated actions will not be available.

Google#

Note

The Google backend requires you to register a project on the Google Cloud Platform and enable the YouTube Data API v3. This plugin will use the OAuth2 authentication provided by the Google plugin, and quota limits apply.

Note

The Google backend doesn’t support get_feed(). The YouTube Data API v3 does not support an endpoint to retrieve the feed, and the alternative (searching for all the recent videos of all the subscribed channels) would be too slow, besides probably burning the whole YouTube API quota.

Follow the same instructions as other Google plugins. Create a project, enable the YouTube Data API v3, and download the credentials file to <workdir>/credentials/google/client_secret.json.

Authentication will be performed the first time you run the plugin.

It can be run:

  • Automatically: when the plugin is started, it will open an authentication page if the BROWSER environment variable is set. Otherwise, it will log the URL that should be opened in a browser to authenticate the plugin. You can also copy the authenticated session to other machines by copying the <workdir>/credentials/google folder.

  • Manually: by running the platypush.plugins.google.credentials command (see documentation of other Google plugins). Note that if you opt to generate the credentials manually, you will need a token with the following scopes:

    • https://www.googleapis.com/auth/youtube

    • https://www.googleapis.com/auth/youtube.force-ssl

Configuration#

youtube:
  # [Optional]
  # Configuration for the backends.
  # backends:   # type=Optional[Dict[str, dict]]

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(backends: Dict[str, dict] | None = None, **kwargs)[source]#

Bases: Plugin

YouTube plugin.

This plugin supports multiple backends to interact with YouTube:

  • piped: Uses a Piped instance.

  • invidious: Uses an Invidious

    instance.

  • google: Uses the official Google YouTube API.

You can specify the backend configuration in the plugin configuration through the backends parameter:

youtube:
    backends:
        # For Piped
        piped:
            instance_url: https://pipedapi.kavin.rocks
            auth_token: <auth_token>
            frontend_url: https://piped.kavin.rocks

        # For Invidious
        invidious:
            instance_url: https://yewtu.be
            auth_token: <auth_token>

        # For the official YouTube API
        google:
            # OAuth authentication will be performed through the Google plugin
            # the first time you run the plugin.

Piped#

Warning

At the time of writing (February 2025), the Piped backend isn’t actively tested. That’s because most of the instances seem to be either down or blocked by Google. invidious is the recommended backend.

Parameters:

  • instance_url: Base URL of the Piped instance (default: https://pipedapi.kavin.rocks). NOTE: This should be the URL of the Piped API, not the Piped instance/frontend itself.

  • 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.

  • frontend_url: Optional URL of the Piped frontend. This is needed to generate channels and playlists URLs. If not provided, the plugin will try and infer it by stripping the api string from instance_url.

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.

Invidious#

Parameters:

  • instance_url: Base URL of the Invidious instance (default: https://yewtu.be).

  • auth_token: Optional authentication token from the Invidious 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 Invidious instance.

  2. Open the URL https://<instance_url>/authorize_token?scopes=:* in your browser. Replace <instance_url> with the URL of your Invidious instance, and :* with the scopes you want to assign to the token (although an all-access token is recommended for full functionality).

  3. Copy the generated token.

If both are provided, the Invidious backend will be used.

If none is provided, the plugin will fallback to the default Invidious instance (https://yewtu.be), but authenticated actions will not be available.

Google#

Note

The Google backend requires you to register a project on the Google Cloud Platform and enable the YouTube Data API v3. This plugin will use the OAuth2 authentication provided by the Google plugin, and quota limits apply.

Note

The Google backend doesn’t support get_feed(). The YouTube Data API v3 does not support an endpoint to retrieve the feed, and the alternative (searching for all the recent videos of all the subscribed channels) would be too slow, besides probably burning the whole YouTube API quota.

Follow the same instructions as other Google plugins. Create a project, enable the YouTube Data API v3, and download the credentials file to <workdir>/credentials/google/client_secret.json.

Authentication will be performed the first time you run the plugin.

It can be run:

  • Automatically: when the plugin is started, it will open an authentication page if the BROWSER environment variable is set. Otherwise, it will log the URL that should be opened in a browser to authenticate the plugin. You can also copy the authenticated session to other machines by copying the <workdir>/credentials/google folder.

  • Manually: by running the platypush.plugins.google.credentials command (see documentation of other Google plugins). Note that if you opt to generate the credentials manually, you will need a token with the following scopes:

    • https://www.googleapis.com/auth/youtube

    • https://www.googleapis.com/auth/youtube.force-ssl

__init__(backends: Dict[str, dict] | None = None, **kwargs)[source]#
Parameters:

backends – Configuration for the backends.

add_to_playlist(playlist_id: str, item_ids: Collection[str] | None = None, backend: str | None = None, **kwargs)[source]#

Add a video to a playlist.

Parameters:

  • playlist_id – Playlist ID.

  • item_ids – YouTube IDs or URLs to add to the playlist.

  • backend – Optional backend to use. If not specified, the default one will be used.

create_playlist(name: str, privacy: str | None = 'private', backend: str | None = None) → dict[source]#

Create a new playlist.

Parameters:

  • name – Playlist name.

  • backend – Optional backend to use. If not specified, the default one will be used.

  • privacy –

    Privacy level of the playlist (only supported by Invidious). Supported values are:

    • private: Only you can see the playlist.

    • public: Everyone can see the playlist.

    • unlisted: Everyone with the link can see the playlist.

Returns:

Playlist information.

delete_playlist(id: str, backend: str | None = None)[source]#

Delete a playlist.

Parameters:

  • id – Playlist ID.

  • backend – Optional backend to use. If not specified, the default one will be used.

edit_playlist(id: str, name: str | None = None, description: str | None = None, privacy: str | None = None, backend: str | None = None)[source]#

Edit a playlist.

Parameters:

  • id – Playlist ID.

  • name – New playlist name.

  • description – New playlist description.

  • privacy –

    New privacy level of the playlist (only supported by Invidious). Supported values are:

    • private: Only you can see the playlist.

    • public: Everyone can see the playlist.

    • unlisted: Everyone with the link can see the playlist.

  • backend – Optional backend to use. If not specified, the default one will be used.

get_channel(id: str, page: str | None = None, backend: str | None = None) → dict[source]#

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

Parameters:

  • id – Channel ID or URL.

  • page – (Optional) ID/index of the page to retrieve.

  • backend – Optional backend to use. If not specified, the default one will be used.

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",
  "item_type": "channel",
  "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",
      "item_type": "video",
      "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(page: Any | None = None, backend: str | None = None) → List[dict][source]#

Retrieve the YouTube feed.

If you use the piped backend, depending on your account settings on the configured Piped instance, this may return either the latest videos uploaded by your subscribed channels (if you provided an authentication token), or the trending videos in the configured area (if you didn’t).

If you use the invidious backend, this requires the user to be authenticated - it will return the latest videos uploaded by the subscribed channels.

If you use the google backend, this method is not supported - the native YouTube API doesn’t provide an endpoint to retrieve the feed, and the alternative (searching for all the recent videos of all the subscribed channels) would be too slow, besides probably burning the whole YouTube API quota.

Parameters:

  • page – (Optional) ID/index of the page to retrieve. This isn’t supported by the Piped backend (all the videos are returned at once), and it’s instead an integer >= 1 on the Invidious backend.

  • backend – Optional backend to use. If not specified, the default one will be used.

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",
    "item_type": "video",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]

get_playlist(id: str, backend: str | None = None, page: Any | None = None) → List[dict][source]#

Retrieve the videos in a playlist.

Parameters:

  • id – Playlist ID as returned by the backend.

  • backend – Optional backend to use. If not specified, the default one will be used.

  • page – (Optional) ID/index of the page to retrieve. This is only supported by the YouTube backend. Both the Piped and Invidious backends will return all the videos at once.

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",
    "item_type": "video",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]

get_playlists(backend: str | None = None, page: Any | None = None) → List[dict][source]#

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

Parameters:

  • backend – Optional backend to use. If not specified, the default one will be used.

  • page – (Optional) ID/index of the page to retrieve. This is only supported by the YouTube backend. Both the Piped and Invidious backends will return all the playlists at once.

Returns:

[
  {
    "channel": "My Channel",
    "channel_image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "channel_url": "https://youtube.com/channel/1234567890",
    "description": "My video description",
    "id": "12345678-1234-1234-1234-1234567890ab",
    "image": "https://i.ytimg.com/vi/1234567890/hqdefault.jpg",
    "item_type": "playlist",
    "name": "My Playlist Name",
    "url": "https://youtube.com/playlist?list=1234567890",
    "videos": 10
  }
]

get_subscriptions(backend: str | None = None, page: Any | None = None) → List[dict][source]#

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

Parameters:

  • backend – Optional backend to use. If not specified, the default one will be used.

  • page – (Optional) ID/index of the page to retrieve. This is only supported by the YouTube backend. Both the Piped and Invidious backends will return all the subscriptions at once.

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",
    "item_type": "channel",
    "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",
        "item_type": "video",
        "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"
  }
]

is_subscribed(channel_id: str, backend: str | None = None) → bool[source]#

Check if the user is subscribed to a channel.

Parameters:

  • channel_id – YouTube channel ID.

  • backend – Optional backend to use. If not specified, the default one will be used.

Returns:

True if the user is subscribed to the channel, False otherwise.

remove_from_playlist(playlist_id: str, item_ids: Collection[str] | None = None, indices: Collection[int] | None = None, backend: str | None = None, **kwargs)[source]#

Remove a video from a playlist.

Note that either item_ids or indices must be provided.

piped and invidious backends support both item_ids and indices. google backend only supports item_ids, and they must match item_id fields returned by get_playlist().

Parameters:

  • item_ids – YouTube video IDs or URLs to remove from the playlist.

  • indices – (0-based) indices of the items in the playlist to remove.

  • playlist_id – Playlist ID.

  • backend – Optional backend to use. If not specified, the default one will be used.

search(query: str, backend: str | None = None, **_) → List[dict][source]#

Search for YouTube videos.

Parameters:

  • query – Query string.

  • backend – Optional backend to use. If not specified, the default one will be used.

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",
    "item_type": "video",
    "title": "My Video Title",
    "url": "https://youtube.com/watch?v=1234567890"
  }
]

subscribe(channel_id: str, backend: str | None = None)[source]#

Subscribe to a channel.

Parameters:

  • channel_id – YouTube channel ID.

  • backend – Optional backend to use. If not specified, the default one will be used.

unsubscribe(channel_id: str, backend: str | None = None)[source]#

Unsubscribe from a channel.

Parameters:

  • channel_id – YouTube channel ID.

  • backend – Optional backend to use. If not specified, the default one will be used.