youtube

`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#

youtube.add_to_playlist

youtube.create_playlist

youtube.delete_playlist

youtube.get_channel

youtube.get_feed

youtube.get_playlist

youtube.get_playlists

youtube.get_subscriptions

youtube.is_subscribed

youtube.remove_from_playlist

youtube.rename_playlist

youtube.search

youtube.subscribe

youtube.unsubscribe

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.

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.

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

Add a video to a playlist.

Parameters:

playlist_id – Piped playlist ID.
item_ids – YouTube IDs or URLs to add to the playlist.

create_playlist(name: str) → dict[source]#

Create a new playlist.

Parameters:: name – Playlist name.
Returns:: Playlist information.

delete_playlist(id: str)[source]#

Delete a playlist.

Parameters:: id – Piped playlist ID.

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",
  "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() → 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",
    "item_type": "video",
    "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",
    "item_type": "video",
    "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:

[
  {
    "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() → 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",
    "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) → bool[source]#

Check if the user is subscribed to a channel.

Parameters:: channel_id – YouTube channel ID.
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, **kwargs)[source]#

Remove a video from a playlist.

Note that either item_ids or indices must be provided.

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 – Piped playlist ID.

rename_playlist(id: str, name: str | None = None, description: str | None = None)[source]#

Rename a playlist.

Parameters:

id – Piped playlist ID.
name – New playlist name.
description – New playlist description.

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

subscribe(channel_id: str)[source]#

Subscribe to a channel.

Parameters:: channel_id – YouTube channel ID.

unsubscribe(channel_id: str)[source]#

Unsubscribe from a channel.

Parameters:: channel_id – YouTube channel ID.

youtube

Platypush documentation

youtube#

Description#

Configuration#

Dependencies#

Actions#

Module reference#

`youtube`#