music.tidal

Platypush documentation

`music.tidal`#

Description#

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.

Configuration#

music.tidal:
  # [Optional]
  # Default audio quality. Default: ``high``.
  # Supported: [``loseless``, ``master``, ``high``, ``low``].
  # quality: high  # type=str

  # [Optional]
  # Path to the file where the OAuth session
  # parameters will be stored (default:
  # ``<WORKDIR>/tidal/credentials.json``).
  # credentials_file: /var/lib/platypush/tidal/credentials.json  # type=str

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install tidalapi >= 0.7.0

Triggered events#

platypush.message.event.music.tidal.TidalPlaylistUpdatedEvent

Module reference#

class platypush.plugins.music.tidal.MusicTidalPlugin(quality: str = 'high', credentials_file: str = '/var/lib/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.

__init__(quality: str = 'high', credentials_file: str = '/var/lib/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": "2020-01-01T00:00:00+00:00",
  "description": "string",
  "duration": "Playlist duration, in seconds",
  "id": "2b288612-34f5-11ed-b42d-001500e8f607",
  "last_updated_at": "2020-01-01T00:00:00+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"
}

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": "2020-01-01T00:00:00+00:00",
  "description": "string",
  "duration": "Playlist duration, in seconds",
  "id": "2b288612-34f5-11ed-b42d-001500e8f607",
  "last_updated_at": "2020-01-01T00:00:00+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": "2020-01-01T00:00:00+00:00",
    "description": "string",
    "duration": "Playlist duration, in seconds",
    "id": "2b288612-34f5-11ed-b42d-001500e8f607",
    "last_updated_at": "2020-01-01T00:00:00+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"
  }
]

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: int | str | 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": "2020-01-01T00:00:00+00:00",
      "description": "string",
      "duration": "Playlist duration, in seconds",
      "id": "2b288612-34f5-11ed-b42d-001500e8f607",
      "last_updated_at": "2020-01-01T00:00:00+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"
    }
  ]
}

start()#: Start the plugin.

stop()#: Stop the plugin.

wait_stop(timeout=None)#: Wait until a stop event is received.

music.tidal

Platypush documentation

music.tidal#

Description#

Configuration#

Dependencies#

Triggered events#

Actions#

Module reference#

`music.tidal`#