music.tidal#

class platypush.plugins.music.tidal.MusicTidalPlugin(quality: str = 'high', credentials_file: str = '/home/blacklight/.local/share/platypush/tidal/credentials.json', **kwargs)[source]#

Bases: RunnablePlugin

Plugin to interact with the user’s Tidal account and library.

Upon the first login, the application will prompt you with a link to connect to your Tidal account. Once authorized, you should no longer be required to explicitly login.

Triggers:

  • platypush.message.event.music.TidalPlaylistUpdatedEvent: when a user playlist is updated.

Requires:

  • tidalapi (pip install 'tidalapi >= 0.7.0')

__init__(quality: str = 'high', credentials_file: str = '/home/blacklight/.local/share/platypush/tidal/credentials.json', **kwargs)[source]#
Parameters:

  • quality – Default audio quality. Default: high. Supported: [loseless, master, high, low].

  • credentials_file – Path to the file where the OAuth session parameters will be stored (default: <WORKDIR>/tidal/credentials.json).

add_album(album_id: str | int)[source]#

Add an album to the user’s collection.

Parameters:

album_id – Album ID.

add_artist(artist_id: str | int)[source]#

Add an artist to the user’s collection.

Parameters:

artist_id – Artist ID.

add_playlist(playlist_id: str)[source]#

Add a playlist to the user’s collection.

Parameters:

playlist_id – Playlist ID.

add_to_playlist(playlist_id: str, track_ids: Iterable[str | int])[source]#

Append one or more tracks to a playlist.

Parameters:

  • playlist_id – Target playlist ID.

  • track_ids – List of track IDs to append.

add_track(track_id: str | int)[source]#

Add a track to the user’s collection.

Parameters:

track_id – Track ID.

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

Create a new playlist.

Parameters:

  • name – Playlist name.

  • description – Optional playlist description.

Returns:

{
  "created_at": "2023-05-10T22:44:51.370169+00:00",
  "description": "string",
  "duration": "Playlist duration, in seconds",
  "id": "2b288612-34f5-11ed-b42d-001500e8f607",
  "last_updated_at": "2023-05-10T22:44:51.370194+00:00",
  "name": "string",
  "num_tracks": 42,
  "owner": "Playlist creator/owner ID",
  "public": true,
  "tracks": [
    {
      "album": {
        "artist": {
          "id": "3288612",
          "name": "string",
          "url": "https://tidal.com/artist/3288612"
        },
        "duration": "Album duration, in seconds",
        "id": "45288612",
        "name": "string",
        "num_tracks": 10,
        "tracks": [
          {
            "key": "value"
          }
        ],
        "url": "https://tidal.com/album/45288612",
        "year": 2003
      },
      "artist": {
        "id": "3288612",
        "name": "string",
        "url": "https://tidal.com/artist/3288612"
      },
      "duration": "Track duration, in seconds",
      "id": "25288614",
      "name": "Track title",
      "track_num": "Index of the track within the album",
      "url": "https://tidal.com/track/25288614"
    }
  ],
  "url": "https://tidal.com/playlist/2b288612-34f5-11ed-b42d-001500e8f607"
}

delete_playlist(playlist_id: str)[source]#

Delete a playlist by ID.

Parameters:

playlist_id – ID of the playlist to delete.

edit_playlist(playlist_id: str, title=None, description=None)[source]#

Edit a playlist’s metadata.

Parameters:

  • name – New name.

  • description – New description.

get_album(album_id: str | int)[source]#

Get the details of an album.

Parameters:

artist_id – Album ID.

Returns:

{
  "artist": {
    "id": "3288612",
    "name": "string",
    "url": "https://tidal.com/artist/3288612"
  },
  "duration": "Album duration, in seconds",
  "id": "45288612",
  "name": "string",
  "num_tracks": 10,
  "tracks": [
    {
      "key": "value"
    }
  ],
  "url": "https://tidal.com/album/45288612",
  "year": 2003
}

get_artist(artist_id: str | int)[source]#

Get the details of an artist.

Parameters:

artist_id – Artist ID.

Returns:

{
  "id": "3288612",
  "name": "string",
  "url": "https://tidal.com/artist/3288612"
}

get_download_url(track_id: str) → str[source]#

Get the direct download URL of a track.

Parameters:

artist_id – Track ID.

get_playlist(playlist_id: str)[source]#

Get the details of a playlist (including tracks).

Parameters:

playlist_id – Playlist ID.

Returns:

{
  "created_at": "2023-05-10T22:44:51.370169+00:00",
  "description": "string",
  "duration": "Playlist duration, in seconds",
  "id": "2b288612-34f5-11ed-b42d-001500e8f607",
  "last_updated_at": "2023-05-10T22:44:51.370194+00:00",
  "name": "string",
  "num_tracks": 42,
  "owner": "Playlist creator/owner ID",
  "public": false,
  "tracks": [
    {
      "album": {
        "artist": {
          "id": "3288612",
          "name": "string",
          "url": "https://tidal.com/artist/3288612"
        },
        "duration": "Album duration, in seconds",
        "id": "45288612",
        "name": "string",
        "num_tracks": 10,
        "tracks": [
          {
            "key": "value"
          }
        ],
        "url": "https://tidal.com/album/45288612",
        "year": 2003
      },
      "artist": {
        "id": "3288612",
        "name": "string",
        "url": "https://tidal.com/artist/3288612"
      },
      "duration": "Track duration, in seconds",
      "id": "25288614",
      "name": "Track title",
      "track_num": "Index of the track within the album",
      "url": "https://tidal.com/track/25288614"
    }
  ],
  "url": "https://tidal.com/playlist/2b288612-34f5-11ed-b42d-001500e8f607"
}

get_playlists()[source]#

Get the user’s playlists (track lists are excluded).

Returns:

[
  {
    "created_at": "2023-05-10T22:44:51.370169+00:00",
    "description": "string",
    "duration": "Playlist duration, in seconds",
    "id": "2b288612-34f5-11ed-b42d-001500e8f607",
    "last_updated_at": "2023-05-10T22:44:51.370194+00:00",
    "name": "string",
    "num_tracks": 42,
    "owner": "Playlist creator/owner ID",
    "public": false,
    "tracks": [
      {
        "album": {
          "artist": {
            "id": "3288612",
            "name": "string",
            "url": "https://tidal.com/artist/3288612"
          },
          "duration": "Album duration, in seconds",
          "id": "45288612",
          "name": "string",
          "num_tracks": 10,
          "tracks": [
            {
              "key": "value"
            }
          ],
          "url": "https://tidal.com/album/45288612",
          "year": 2003
        },
        "artist": {
          "id": "3288612",
          "name": "string",
          "url": "https://tidal.com/artist/3288612"
        },
        "duration": "Track duration, in seconds",
        "id": "25288614",
        "name": "Track title",
        "track_num": "Index of the track within the album",
        "url": "https://tidal.com/track/25288614"
      }
    ],
    "url": "https://tidal.com/playlist/2b288612-34f5-11ed-b42d-001500e8f607"
  }
]

get_track(track_id: str | int)[source]#

Get the details of an track.

Parameters:

artist_id – Track ID.

Returns:

{
  "album": {
    "artist": {
      "id": "3288612",
      "name": "string",
      "url": "https://tidal.com/artist/3288612"
    },
    "duration": "Album duration, in seconds",
    "id": "45288612",
    "name": "string",
    "num_tracks": 10,
    "tracks": [
      {
        "key": "value"
      }
    ],
    "url": "https://tidal.com/album/45288612",
    "year": 2003
  },
  "artist": {
    "id": "3288612",
    "name": "string",
    "url": "https://tidal.com/artist/3288612"
  },
  "duration": "Track duration, in seconds",
  "id": "25288614",
  "name": "Track title",
  "track_num": "Index of the track within the album",
  "url": "https://tidal.com/track/25288614"
}

main()[source]#

Implementation of the main loop of the plugin.

remove_album(album_id: str | int)[source]#

Remove an album from the user’s collection.

Parameters:

album_id – Album ID.

remove_artist(artist_id: str | int)[source]#

Remove an artist from the user’s collection.

Parameters:

artist_id – Artist ID.

remove_from_playlist(playlist_id: str, track_id: str | int | None = None, index: int | None = None)[source]#

Remove a track from a playlist.

Specify either the track_id or the index.

Parameters:

  • playlist_id – Target playlist ID.

  • track_id – ID of the track to remove.

  • index – Index of the track to remove.

remove_playlist(playlist_id: str)[source]#

Remove a playlist from the user’s collection.

Parameters:

playlist_id – Playlist ID.

remove_track(track_id: str | int)[source]#

Remove a track from the user’s collection.

Parameters:

track_id – Track ID.

search(query: str, limit: int = 50, offset: int = 0, type: str | None = None)[source]#

Perform a search.

Parameters:

  • query – Query string.

  • limit – Maximum results that should be returned (default: 50).

  • offset – Search offset (default: 0).

  • type – Type of results that should be returned. Default: None (return all the results that match the query). Supported: artist, album, track and playlist.

Returns:

{
  "albums": [
    {
      "artist": {
        "id": "3288612",
        "name": "string",
        "url": "https://tidal.com/artist/3288612"
      },
      "duration": "Album duration, in seconds",
      "id": "45288612",
      "name": "string",
      "num_tracks": 10,
      "tracks": [
        {
          "key": "value"
        }
      ],
      "url": "https://tidal.com/album/45288612",
      "year": 2003
    }
  ],
  "artists": [
    {
      "id": "3288612",
      "name": "string",
      "url": "https://tidal.com/artist/3288612"
    }
  ],
  "playlists": [
    {
      "created_at": "2023-05-10T22:44:51.370169+00:00",
      "description": "string",
      "duration": "Playlist duration, in seconds",
      "id": "2b288612-34f5-11ed-b42d-001500e8f607",
      "last_updated_at": "2023-05-10T22:44:51.370194+00:00",
      "name": "string",
      "num_tracks": 42,
      "owner": "Playlist creator/owner ID",
      "public": true,
      "tracks": [
        {
          "album": {
            "artist": {
              "id": "3288612",
              "name": "string",
              "url": "https://tidal.com/artist/3288612"
            },
            "duration": "Album duration, in seconds",
            "id": "45288612",
            "name": "string",
            "num_tracks": 10,
            "tracks": [
              {
                "key": "value"
              }
            ],
            "url": "https://tidal.com/album/45288612",
            "year": 2003
          },
          "artist": {
            "id": "3288612",
            "name": "string",
            "url": "https://tidal.com/artist/3288612"
          },
          "duration": "Track duration, in seconds",
          "id": "25288614",
          "name": "Track title",
          "track_num": "Index of the track within the album",
          "url": "https://tidal.com/track/25288614"
        }
      ],
      "url": "https://tidal.com/playlist/2b288612-34f5-11ed-b42d-001500e8f607"
    }
  ],
  "tracks": [
    {
      "album": {
        "artist": {
          "id": "3288612",
          "name": "string",
          "url": "https://tidal.com/artist/3288612"
        },
        "duration": "Album duration, in seconds",
        "id": "45288612",
        "name": "string",
        "num_tracks": 10,
        "tracks": [
          {
            "key": "value"
          }
        ],
        "url": "https://tidal.com/album/45288612",
        "year": 2003
      },
      "artist": {
        "id": "3288612",
        "name": "string",
        "url": "https://tidal.com/artist/3288612"
      },
      "duration": "Track duration, in seconds",
      "id": "25288614",
      "name": "Track title",
      "track_num": "Index of the track within the album",
      "url": "https://tidal.com/track/25288614"
    }
  ]
}