ytmusicapi

https://ytmusicapi.readthedocs.io/
Admin
ytmusicapi is an unofficial Python API for YouTube Music that enables automation of library...
Tokens:103,715
Snippets:722
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### setup()

Source: https://ytmusicapi.readthedocs.io/en/stable/index.html

Guides the user through the setup process to generate authentication headers or file.

```APIDOC
## setup()

### Description
Guides the user through the setup process to generate authentication headers or file.

### Method
Function

### Signature
`setup(filepath=None, headers_raw=None, open_browser=False)`

### Parameters
- **filepath** (str, optional) - Path to save authentication file.
- **headers_raw** (str, optional) - Raw headers string from browser.
- **open_browser** (bool, optional) - Whether to open browser for OAuth.

### Example
```python
from ytmusicapi import setup
setup()
```
```

--------------------------------

### User page example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/browsing.html

Example dictionary returned by get_user, containing name, videos, and playlists sections with browseId and params.

```json
{
  "name": "4Tune - No Copyright Music",
  "videos": {
    "browseId": "UC44hbeRoCZVVMVg5z0FfIww",
    "results": [
      {
        "title": "Epic Music Soundtracks 2019",
        "videoId": "bJonJjgS2mM",
        "playlistId": "RDAMVMbJonJjgS2mM",
        "thumbnails": [
          {
            "url": "https://i.ytimg.com/vi/bJon...",
            "width": 800,
            "height": 450
          }
        ],
        "views": "19K"
      }
    ]
  },
  "playlists": {
    "browseId": "UC44hbeRoCZVVMVg5z0FfIww",
    "results": [
      {
        "title": "♚ Machinimasound | Playlist",
        "playlistId": "PLRm766YvPiO9ZqkBuEzSTt6Bk4eWIr3gB",
        "thumbnails": [
          {
            "url": "https://i.ytimg.com/vi/...",
            "width": 400,
            "height": 225
          }
        ]
      }
    ],
    "params": "6gO3AUNvWU..."
  }
}
```

--------------------------------

### setup

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/reference/setup.rst.txt

Initializes the ytmusicapi client with the necessary authentication and configuration.

```APIDOC
## setup

### Description
Initializes the ytmusicapi client with the necessary authentication and configuration.

### Method
setup

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### get_charts() example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/explore.html

Example dictionary returned by get_charts(), showing countries, videos, artists, and genres sections with sample data.

```python
{
    "countries": {
        "selected": {
            "text": "United States"
        },
        "options": ["DE",
            "ZZ",
            "ZW"]
    },
    "videos": [
        {
            "title": "Daily Top Music Videos - United States",
            "playlistId": "PL4fGSI1pDJn61unMfmrUSz68RT8IFFnks",
            "thumbnails": []
        }
    ],
    "artists": [
        {
            "title": "YoungBoy Never Broke Again",
            "browseId": "UCR28YDxjDE3ogQROaNdnRbQ",
            "subscribers": "9.62M",
            "thumbnails": [],
            "rank": "1",
            "trend": "neutral"
        }
    ],
    "genres": [
        {
            "title": "Top 50 Pop Music Videos United States",
            "playlistId": "PL4fGSI1pDJn77aK7sAW2AT0oOzo5inWY8",
            "thumbnails": []
        }
    ]
}
```

--------------------------------

### ytmusicapi.setup.parse_args

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Parses command-line arguments for the setup tool.

```APIDOC
## parse_args

### Description
Parses command-line arguments for the setup tool.

### Method
Function

### Signature
`parse_args(args: list[str]) -> argparse.Namespace`

### Parameters
- **args** (list[str]) - Required - The list of command-line arguments.

### Return Type
`Namespace`

### Returns
An argparse.Namespace containing the parsed arguments.
```

--------------------------------

### Install ytmusicapi with pip

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/setup/index.rst.txt

Run this command to install the ytmusicapi package. This is the only setup required for basic usage.

```bash
pip install ytmusicapi
```

--------------------------------

### ytmusicapi.setup.main

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Main entry point for the setup command-line tool. Returns a token or configuration string.

```APIDOC
## main

### Description
Main entry point for the setup command-line tool. Returns a token or configuration string.

### Method
Function

### Signature
`main() -> ytmusicapi.auth.oauth.token.RefreshingToken | str`

### Parameters
None

### Return Type
`RefreshingToken | str`

### Returns
A RefreshingToken or a configuration string.
```

--------------------------------

### get_podcast() example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/podcasts.html

Example dictionary returned by YTMusic.get_podcast() showing podcast metadata and episodes.

```json
{
    "author":
    {
        "name": "Stanford Graduate School of Business",
        "id": "UCGwuxdEeCf0TIA2RbPOj-8g"
    },
    "title": "Think Fast, Talk Smart: The Podcast",
    "description": "Join Matt Abrahams, a lecturer of...",
    "saved": false,
    "episodes":
    [
        {
            "index": 0,
            "title": "132. Lean Into Failure: How to Make Mistakes That Work | Think Fast, Talk Smart: Communication...",
            "description": "Effective and productive teams and...",
            "duration": "25 min",
            "videoId": "xAEGaW2my7E",
            "browseId": "MPEDxAEGaW2my7E",
            "videoType": "MUSIC_VIDEO_TYPE_PODCAST_EPISODE",
            "date": "Mar 5, 2024",
            "thumbnails": [...]
        }
    ]
}
```

--------------------------------

### ytmusicapi.setup module

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/index.html

Setup functions for initializing ytmusicapi and OAuth.

```APIDOC
## ytmusicapi.setup

### Functions
- `main()`
- `parse_args()`
- `setup()`
- `setup_oauth()`
```

--------------------------------

### ytmusicapi browser command

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/setup/browser.rst.txt

Run this command in a console to start the interactive setup. Follow the prompts and paste the request headers copied from your browser.

```bash
ytmusicapi browser
```

--------------------------------

### get_channel() example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/podcasts.html

Example dictionary returned by YTMusic.get_channel() showing channel info with episodes and podcasts sections.

```json
{
    "title": 'Stanford Graduate School of Business',
    "thumbnails": [...]
    "episodes":
    {
        "browseId": "UCGwuxdEeCf0TIA2RbPOj-8g",
        "results":
        [
            {
                "index": 0,
                "title": "The Brain Gain: The Impact of Immigration on American Innovation with Rebecca Diamond",
                "description": "Immigrants' contributions to America ...",
                "duration": "24 min",
                "videoId": "TS3Ovvk3VAA",
                "browseId": "MPEDTS3Ovvk3VAA",
                "videoType": "MUSIC_VIDEO_TYPE_PODCAST_EPISODE",
                "date": "Mar 6, 2024",
                "thumbnails": [...]
            },
        ],
        "params": "6gPiAUdxWUJXcFlCQ3BN..."
    },
    "podcasts":
    {
        "browseId": null,
        "results":
        [
            {
                "title": "Stanford GSB Podcasts",
                "channel":
                {
                    "id": "UCGwuxdEeCf0TIA2RbPOj-8g",
                    "name": "Stanford Graduate School of Business"
                },
                "browseId": "MPSPPLxq_lXOUlvQDUNyoBYLkN8aVt5yAwEtG9",
                "podcastId": "PLxq_lXOUlvQDUNyoBYLkN8aVt5yAwEtG9",
                "thumbnails": [...]
            }
       ]
    }
}
```

--------------------------------

### Album metadata example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/browsing.html

Example dictionary returned by the album browsing method, showing fields like title, type, artists, tracks, and other_versions.

```json
{
  "title": "Revival",
  "type": "Album",
  "thumbnails": [],
  "description": "Revival is the...",
  "descriptionRuns": [
      {"text": "Revival is the..."},
  ],
  "artists": [
    {
      "name": "Eminem",
      "id": "UCedvOgsKFzcK3hA5taf3KoQ"
    }
  ],
  "year": "2017",
  "trackCount": 19,
  "duration": "1 hour, 17 minutes",
  "audioPlaylistId": "OLAK5uy_nMr9h2VlS-2PULNz3M3XVXQj_P3C2bqaY",
  "tracks": [
    {
      "videoId": "iKLU7z_xdYQ",
      "title": "Walk On Water (feat. Beyoncé)",
      "artists": [
        {
          "name": "Eminem",
          "id": "UCedvOgsKFzcK3hA5taf3KoQ"
        }
      ],
      "album": "Revival",
      "likeStatus": "INDIFFERENT",
      "thumbnails": null,
      "isAvailable": true,
      "isExplicit": true,
      "duration": "5:03",
      "duration_seconds": 303,
      "trackNumber": 0,
      "inLibrary": false,
      "feedbackTokens": {
        "add": "AB9zfpK...",
        "remove": "AB9zfpK..."
      },
      "pinnedToListenAgain": false,
      "listenAgainFeedbackTokens": {
        "pin": "AB9zfpJ...",
        "unpin": "AB9zfpL..."
      },
      "creditsBrowseId": "MPTCiKLU7z_xdYQ"
    }
  ],
  "other_versions": [
    {
      "title": "Revival",
      "year": "Eminem",
      "browseId": "MPREb_fefKFOTEZSp",
      "thumbnails": [...],
      "isExplicit": false
    },
  ],
  "duration_seconds": 4657
}
```

--------------------------------

### get_watch_playlist return value example

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Example of the dictionary returned by get_watch_playlist. Shows the structure with tracks, playlistId, and lyrics. The counterpart key is optional and appears only when a song has a video counterpart.

```json
{
    "tracks": [
        {
          "videoId": "9mWr4c_ig54",
          "title": "Foolish Of Me (feat. Jonathan Mendelsohn)",
          "length": "3:07",
          "thumbnail": [
            {
              "url": "https://lh3.googleusercontent.com/ulK2YaLtOW0PzcN7ufltG6e4ae3WZ9Bvg8CCwhe6LOccu1lCKxJy2r5AsYrsHeMBSLrGJCNpJqXgwczk=w60-h60-l90-rj",
              "width": 60,
              "height": 60
            }...
          ],
          "inLibrary": false,
          "feedbackTokens": {
            "add": "AB9zfpIGg9XN4u2iJ...",
            "remove": "AB9zfpJdzWLcdZtC..."
          },
          "pinnedToListenAgain": true,
          "listenAgainFeedbackTokens": {
            "pin": "AB9zfpK8kP5mQ7rT...",
            "unpin": "AB9zfpLy3L9vB2xN..."
          },
          "likeStatus": "INDIFFERENT",
          "videoType": "MUSIC_VIDEO_TYPE_ATV",
          "artists": [
            {
              "name": "Seven Lions",
              "id": "UCYd2yzYRx7b9FYnBSlbnknA"
            },
            {
              "name": "Jason Ross",
              "id": "UCVCD9Iwnqn2ipN9JIF6B-nA"
            },
            {
              "name": "Crystal Skies",
              "id": "UCTJZESxeZ0J_M7JXyFUVmvA"
            }
          ],
          "album": {
            "name": "Foolish Of Me",
            "id": "MPREb_C8aRK1qmsDJ"
          },
          "year": "2020",
          "counterpart": {
            "videoId": "E0S4W34zFMA",
            "title": "Foolish Of Me [ABGT404] (feat. Jonathan Mendelsohn)",
            "length": "3:07",
            "thumbnail": [...],
            "feedbackTokens": null,
            "likeStatus": "LIKE",
            "artists": [
              {
                "name": "Jason Ross",
                "id": null
              },
              {
                "name": "Seven Lions",
                "id": null
              },
              {
                "name": "Crystal Skies",
                "id": null
              }
            ],
            "views": "6.6K"
          }
        },...
    ],
    "playlistId": "RDAMVM4y33h81phKU",
    "lyrics": "MPLYt_HNNclO0Ddoc-17"
}
```

--------------------------------

### Example response for get_search_suggestions with detailed_runs=False

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the plain text list of search suggestions returned when detailed_runs is False.

```json
[
  "faded",
  "faded alan walker lyrics",
  "faded alan walker",
  "faded remix",
  "faded song",
  "faded lyrics",
  "faded instrumental"
]
```

--------------------------------

### get_home example output

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/browsing.html

Example list returned by YTMusic.get_home(), showing the structure of home page rows with titles and contents. Each content item can be an album, playlist, artist, song, or video result with fields like title, browseId, videoId, and thumbnails.

```json
[
    {
        "title": "Your morning music",
        "contents": [
            { //album result
                "title": "Sentiment",
                "browseId": "MPREb_QtqXtd2xZMR",
                "thumbnails": [...]
            },
            { //playlist result
                "title": "r/EDM top submissions 01/28/2022",
                "playlistId": "PLz7-xrYmULdSLRZGk-6GKUtaBZcgQNwel",
                "thumbnails": [...],
                "description": "redditEDM • 161 songs",
                "count": "161",
                "author": [
                    {
                        "name": "redditEDM",
                        "id": "UCaTrZ9tPiIGHrkCe5bxOGwA"
                    }
                ]
            }
        ]
    },
    {
        "title": "Your favorites",
        "contents": [
            { //artist result
                "title": "Chill Satellite",
                "browseId": "UCrPLFBWdOroD57bkqPbZJog",
                "subscribers": "374",
                "thumbnails": [...]
            }
            { //album result
                "title": "Dragon",
                "year": "Two Steps From Hell",
                "browseId": "MPREb_M9aDqLRbSeg",
                "thumbnails": [...]
            }
        ]
    },
    {
        "title": "Quick picks",
        "contents": [
            { //song quick pick
                "title": "Gravity",
                "videoId": "EludZd6lfts",
                "artists": [{
                        "name": "yetep",
                        "id": "UCSW0r7dClqCoCvQeqXiZBlg"
                    }],
                "thumbnails": [...],
                "album": {
                    "name": "Gravity",
                    "id": "MPREb_D6bICFcuuRY"
                }
            },
            { //video quick pick
                "title": "Gryffin & Illenium (feat. Daya) - Feel Good (L3V3LS Remix)",
                "videoId": "bR5l0hJDnX8",
                "artists": [
                    {
                        "name": "L3V3LS",
                        "id": "UCCVNihbOdkOWw_-ajIYhAbQ"
                    }
                ],
                "thumbnails": [...],
                "views": "10M"
            }
        ]
    }
]
```

--------------------------------

### Example output of get_library_channels()

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/library.html

Shows the structure of the list returned by get_library_channels(). Each item contains browseId, artist, subscribers, and thumbnails.

```json
[
    {
        "browseId": "UCRFF8xw5dg9mL4r5ryFOtKw",
        "artist": "Jumpers Jump",
        "subscribers": "1.54M",
        "thumbnails": [...]
    },
    {
        "browseId": "UCQ3f2_sO3NJyDkuCxCNSOVA",
        "artist": "BROWN BAG",
        "subscribers": "74.2K",
        "thumbnails": [...]
    }
]

```

--------------------------------

### Example response for get_search_suggestions with detailed_runs=True

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the detailed list of dictionaries with runs, bold flags, and feedback tokens when detailed_runs is True.

```json
[
  {
    "text": "faded",
    "runs": [
      {
        "text": "fade",
        "bold": true
      },
      {
        "text": "d"
      }
    ],
    "fromHistory": true,
    "feedbackToken": "AEEJK..."
  },
  {
    "text": "faded alan walker lyrics",
    "runs": [
      {
        "text": "fade",
        "bold": true
      },
      {
        "text": "d alan walker lyrics"
      }
    ],
    "fromHistory": false,
    "feedbackToken": None
  },
  {
    "text": "faded alan walker",
    "runs": [
      {
        "text": "fade",
        "bold": true
      },
      {
        "text": "d alan walker"
      }
    ],
    "fromHistory": false,
    "feedbackToken": None
  },
  ...
]
```

--------------------------------

### get_account_info return format

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Example of the dictionary returned by get_account_info(), containing accountName, channelHandle, and accountPhotoUrl.

```python
{
    "accountName": "Sample User",
    "channelHandle": "@SampleUser
    "accountPhotoUrl": "https://yt3.ggpht.com/sample-user-photo"
}
```

--------------------------------

### ytmusicapi.setup_oauth(client_id, client_secret, filepath=None, session=None, proxies=None, open_browser=False) -> RefreshingToken

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Starts OAuth flow from the terminal and returns a string that can be passed to YTMusic().

```APIDOC
## ytmusicapi.setup_oauth(client_id, client_secret, filepath=None, session=None, proxies=None, open_browser=False) -> RefreshingToken

### Description
Starts OAuth flow from the terminal and returns a string that can be passed to YTMusic().

### Method
Function

### Signature
`ytmusicapi.setup_oauth(client_id: str, client_secret: str, filepath: str | None = None, session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, open_browser: bool = False) -> ytmusicapi.auth.oauth.token.RefreshingToken`

### Parameters
- **client_id** (str) - Used to specify the client_id OAuth should use for authentication flow. If provided, client_secret MUST also be passed or both will be ignored.
- **client_secret** (str) - Same as client_id but for the OAuth client secret.
- **session** (Optional[Session]) - Session to use for authentication.
- **proxies** (Optional[dict[str, str]]) - Proxies to use for authentication.
- **filepath** (Optional[str]) - Optional filepath to store headers to.
- **open_browser** (bool) - If True, open the default browser with the setup link.

### Returns
- **RefreshingToken** - Configuration headers string.
```

--------------------------------

### Example output for get_library_playlists

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the format of each playlist item returned by get_library_playlists. Contains playlistId, title, thumbnails, count, and owned.

```json
{
    'playlistId': 'PLQwVIlKxHM6rz0fDJVv_0UlXGEWf-bFys',
    'title': 'Playlist title',
    'thumbnails': [...],
    'count': '5',
    'owned': True
}
```

--------------------------------

### get_library_artists return format

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Example of an artist item returned by get_library_artists(), showing browseId, artist, subscribers, and thumbnails.

```python
{
  "browseId": "UCxEqaQWosMHaTih-tgzDqug",
  "artist": "WildVibes",
  "subscribers": "2.91K",
  "thumbnails": [...]
}
```

--------------------------------

### headers_auth.json.example

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/setup/browser.rst.txt

Example JSON structure for the authentication headers file. Used in the manual file creation method and in Chromium instructions.

```JSON
{
  "accept": "*/*",
  "accept-encoding": "gzip, deflate, br",
  "accept-language": "en-US,en;q=0.9",
  "authorization": "SAPA",
  "content-type": "application/json",
  "cookie": "...",
  "origin": "https://music.youtube.com",
  "referer": "https://music.youtube.com",
  "user-agent": "Mozilla/5.0 ..."
}
```

--------------------------------

### Example output of get_library_podcasts()

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/library.html

Shows the structure of the list returned by get_library_podcasts(). The first podcast is 'New Episodes' if subscribed to relevant podcasts. Each item contains title, channel, browseId, podcastId, and thumbnails.

```json
[
    {
        "title": "New Episodes",
        "channel":
        {
            "id": null,
            "name": "Auto playlist"
        },
        "browseId": "VLRDPN",
        "podcastId": "RDPN",
        "thumbnails": [...]
    },
    {
        "title": "5 Minuten Harry Podcast",
        "channel":
        {
            "id": "UCDIDXF4WM1qQzerrxeEfSdA",
            "name": "coldmirror"
        },
        "browseId": "MPSPPLDvBqWb1UAGeEt9n6vFH_zdGw65Obf3sH",
        "podcastId": "PLDvBqWb1UAGeEt9n6vFH_zdGw65Obf3sH",
        "thumbnails": [...]
    }
]

```

--------------------------------

### Example output for get_tasteprofile

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the dictionary structure returned by get_tasteprofile(), containing artist names with selectionValue and impressionValue strings.

```json
{
    "Drake": {
        "selectionValue": "tastebuilder_selection=/m/05mt_q"
        "impressionValue": "tastebuilder_impression=/m/05mt_q"
    }
}
```

--------------------------------

### Example song dictionary from get_library_upload_songs

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the format of each item in the list returned by get_library_upload_songs(), including entityId, videoId, artists, title, album, likeStatus, and thumbnails.

```json
{
  "entityId": "t_po_CICr2crg7OWpchDpjPjrBA",
  "videoId": "Uise6RPKoek",
  "artists": [{
    'name': 'Coldplay',
    'id': 'FEmusic_library_privately_owned_artist_detaila_po_CICr2crg7OWpchIIY29sZHBsYXk',
  }],
  "title": "A Sky Full Of Stars",
  "album": "Ghost Stories",
  "likeStatus": "LIKE",
  "thumbnails": [...]
}

```

--------------------------------

### Basic usage example: create playlist, search, and add items

Source: https://ytmusicapi.readthedocs.io/en/stable/index.html

Shows the core workflow of the ytmusicapi library: initialize YTMusic with an OAuth file, create a playlist, search for a song, and add the first result to the playlist. Requires Python 3.10 or higher and an OAuth authentication file (oauth.json).

```python
from ytmusicapi import YTMusic


yt = YTMusic('oauth.json')
playlistId = yt.create_playlist('test', 'test description')
search_results = yt.search('Oasis Wonderwall')
yt.add_playlist_items(playlistId, [search_results[0]['videoId']])

```

--------------------------------

### Example usage of remove_search_suggestions

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Demonstrates how to remove a search suggestion by index using the suggestions list from get_search_suggestions with detailed_runs=True.

```python
# Removing suggestion number 0
suggestions = ytmusic.get_search_suggestions(query="fade", detailed_runs=True)
success = ytmusic.remove_search_suggestions(suggestions=suggestions, indices=[0])
if success:
    print("Suggestion removed successfully")
else:
    print("Failed to remove suggestion")
```

--------------------------------

### get_library_albums return format

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Example of an album item returned by get_library_albums(), showing browseId, playlistId, title, type, thumbnails, artists, and year.

```python
{
  "browseId": "MPREb_G8AiyN7RvFg",
  "playlistId": "OLAK5uy_lKgoGvlrWhX0EIPavQUXxyPed8Cj38AWc",
  "title": "Beautiful",
  "type": "Album",
  "thumbnails": [...],
  "artists": [{
    "name": "Project 46",
    "id": "UCXFv36m62USAN5rnVct9B4g"
  }],
  "year": "2015"
}
```

--------------------------------

### Run ytmusicapi oauth command

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/setup/oauth.rst.txt

Run this command in the terminal after installing ytmusicapi. It will create an oauth.json file in the current directory.

```bash
ytmusicapi oauth
```

--------------------------------

### Example list of uploaded songs from get_library_upload_artist

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the structure of the list returned by get_library_upload_artist(), containing uploaded song dictionaries with entityId, videoId, title, artists, album, likeStatus, and thumbnails.

```json
[
  {
    "entityId": "t_po_CICr2crg7OWpchDKwoakAQ",
    "videoId": "Dtffhy8WJgw",
    "title": "Hold Me (Original Mix)",
    "artists": [
      {
        "name": "Jakko",
        "id": "FEmusic_library_privately_owned_artist_detaila_po_CICr2crg7OWpchIFamFra28"
      }
    ],
    "album": null,
    "likeStatus": "LIKE",
    "thumbnails": [...]
  }
]

```

--------------------------------

### Example album dictionary from get_library_upload_album

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Shows the structure of the dictionary returned by get_library_upload_album(), including title, type, thumbnails, trackCount, duration, audioPlaylistId, and a list of tracks with details like entityId, videoId, title, duration, artists, album, likeStatus, and thumbnails.

```json
{
  "title": "18 Months",
  "type": "Album",
  "thumbnails": [...],
  "trackCount": 7,
  "duration": "24 minutes",
  "audioPlaylistId": "MLPRb_po_55chars",
  "tracks": [
    {
      "entityId": "t_po_22chars",
      "videoId": "FVo-UZoPygI",
      "title": "Feel So Close",
      "duration": "4:15",
      "duration_seconds": 255,
      "artists": None,
      "album": {
        "name": "18 Months",
        "id": "FEmusic_library_privately_owned_release_detailb_po_55chars"
      },
      "likeStatus": "INDIFFERENT",
      "thumbnails": None
    },

```

--------------------------------

### ytmusicapi.setup.setup

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Requests browser headers from the user via command line and returns a string that can be passed to YTMusic().

```APIDOC
## setup

### Description
Requests browser headers from the user via command line and returns a string that can be passed to YTMusic().

### Method
Function

### Signature
`setup(filepath: str | None = None, headers_raw: str | None = None) -> str`

### Parameters
- **filepath** (Optional[str]) - Optional - Optional filepath to store headers to.
- **headers_raw** (Optional[str]) - Optional - Optional request headers copied from browser. Otherwise requested from terminal.

### Return Type
`str`

### Returns
Configuration headers string.
```

--------------------------------

### setup_oauth()

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/modules.html

Sets up OAuth authentication for the library.

```APIDOC
## setup_oauth()

### Description
Sets up OAuth authentication for the library.

### Usage
Call this function to configure OAuth credentials.

```

--------------------------------

### setup_browser

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.auth.html

Sets up browser authentication and returns a string (likely the auth string).

```APIDOC
## setup_browser

### Description
Sets up browser authentication and returns a string (likely the auth string).

### Function Signature
`ytmusicapi.auth.browser.setup_browser(filepath: str | None = None, headers_raw: str | None = None) -> str`

### Parameters
- **filepath** (`str | None`) - Optional - Path to file for storing auth
- **headers_raw** (`str | None`) - Optional - Raw headers string

### Returns
- **str** - Auth string or path.
```

--------------------------------

### Authenticated YTMusic instance with browser or OAuth credentials

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/usage.rst.txt

Instantiates YTMusic with credentials from a JSON file. Use 'browser.json' for browser-based authentication or 'oauth.json' with OAuthCredentials for OAuth. Requires setup as described in the Setup documentation.

```python
from ytmusicapi import YTMusic, OAuthCredentials
ytmusic = YTMusic("browser.json") # or, alternatively
ytmusic = YTMusic("oauth.json", oauth_credentials=OAuthCredentials(client_id=client_id, client_secret=client_secret)
```

--------------------------------

### ytmusicapi.setup(filepath=None, headers_raw=None) -> str

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Requests browser headers from the user via command line and returns a string that can be passed to YTMusic().

```APIDOC
## ytmusicapi.setup(filepath=None, headers_raw=None) -> str

### Description
Requests browser headers from the user via command line and returns a string that can be passed to YTMusic().

### Method
Function

### Signature
`ytmusicapi.setup(filepath: str | None = None, headers_raw: str | None = None) -> str`

### Parameters
- **filepath** (Optional[str]) - Optional filepath to store headers to.
- **headers_raw** (Optional[str]) - Optional request headers copied from browser. Otherwise requested from terminal.

### Returns
- **str** - Configuration headers string.
```

--------------------------------

### YTMusic.get_artist(channelId: str) -> dict[str, Any]

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/browsing.html

Get information about an artist and their top releases (songs, albums, singles, videos, and related artists). The top lists contain pointers for getting the full list of releases.

```APIDOC
## YTMusic.get_artist(channelId: str) -> dict[str, Any]

### Description
Get information about an artist and their top releases (songs, albums, singles, videos, and related artists). The top lists contain pointers for getting the full list of releases.

### Parameters
- **channelId** (`str`) – channel id of the artist

### Return Type
`dict`[`str`, `Any`]

### Possible Content Types
- songs
- albums
- singles
- shows
- videos
- episodes
- podcasts
- related

Each of these content keys in the response contains `results` and possibly `browseId` and `params`.
- For songs/videos, pass the browseId to `get_playlist()`.
- For albums/singles/shows, pass browseId and params to `get_artist_albums()`.
```

--------------------------------

### setup_oauth

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/reference/setup.rst.txt

Initializes the ytmusicapi client using OAuth authentication.

```APIDOC
## setup_oauth

### Description
Initializes the ytmusicapi client using OAuth authentication.

### Method
setup_oauth

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### ytmusicapi.auth.browser

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Functions for browser-based authentication setup.

```APIDOC
## ytmusicapi.auth.browser

### Functions

- `is_browser()`
- `setup_browser()`

```

--------------------------------

### YTMusic.get_liked_songs(limit)

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/library.html

Gets playlist items for the 'Liked Songs' playlist.

```APIDOC
## YTMusic.get_liked_songs(limit)

### Description
Gets playlist items for the 'Liked Songs' playlist.

### Method
GET

### Endpoint
Not applicable (SDK method)

### Parameters
- **limit** (int) - Optional - How many items to return. Default: 100.

### Return Type
`dict[str, Any]`

### Returns
List of playlistItem dictionaries. See `get_playlist()`.
```

--------------------------------

### get_history() -> list[dict[str, Any]]

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Gets your play history in reverse chronological order.

```APIDOC
## get_history() -> list[dict[str, Any]]

### Description
Gets your play history in reverse chronological order.

### Method
GET

### Endpoint
Not specified

### Parameters
None

### Response
#### Success Response
- **playlistItems** (list[dict[str, Any]]) - List of playlistItems, see `get_playlist()`. The additional property `played` indicates when the playlistItem was played. The additional property `feedbackToken` can be used to remove items with `remove_history_items()`.

#### Response Example
Not provided

```

--------------------------------

### get_account_info() -> dict[str, Any]

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Gets information about the currently authenticated user's account.

```APIDOC
## get_account_info() -> dict[str, Any]

### Description
Gets information about the currently authenticated user's account.

### Method
GET

### Endpoint
Not specified

### Parameters
None

### Response
#### Success Response
- **accountName** (str) - User's account name
- **channelHandle** (str) - User's channel handle
- **accountPhotoUrl** (str) - URL of user's account photo

#### Response Example
```
{
    "accountName": "Sample User",
    "channelHandle": "@SampleUser",
    "accountPhotoUrl": "https://yt3.ggpht.com/sample-user-photo"
}
```

```

--------------------------------

### PlaylistsMixin.create_playlist()

Source: https://ytmusicapi.readthedocs.io/en/stable/index.html

Creates a new playlist.

```APIDOC
## PlaylistsMixin.create_playlist()

### Description
Creates a new playlist.

### Method
PlaylistsMixin.create_playlist()

### Parameters
- **title** (str) - Required - The title of the playlist.
- **description** (str) - Optional - The description of the playlist.
- **privacyStatus** (str) - Optional - The privacy status: PRIVATE, PUBLIC, or UNLISTED.
- **videoIds** (list) - Optional - A list of video IDs to add to the playlist.
- **sourcePlaylistId** (str) - Optional - The ID of a source playlist to copy items from.

### Returns
str - The ID of the created playlist.
```

--------------------------------

### ytmusicapi.setup with headers_raw

Source: https://ytmusicapi.readthedocs.io/en/stable/_sources/setup/browser.rst.txt

Use this Python code to set up authentication without terminal interaction. Pass the request headers as the headers_raw parameter. The function returns a JSON string with credentials, or creates a file if filepath is provided.

```python
import ytmusicapi
ytmusicapi.setup(filepath="browser.json", headers_raw="<headers copied above>")
```

--------------------------------

### get_album_browse_id(audioPlaylistId: str) -> str | None

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Get an album's browseId based on its audioPlaylistId.

```APIDOC
## get_album_browse_id(audioPlaylistId: str) -> str | None

### Description
Get an album's browseId based on its audioPlaylistId.

### Method
GET

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
- **audioPlaylistId** (str) - Required - id of the audio playlist (starting with OLAK5uy_)

### Return Type
`Optional[str]`

### Returns
browseId (starting with `MPREb_`)
```

--------------------------------

### RefreshingToken.prompt_for_token(credentials, open_browser, to_file)

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.auth.oauth.html

Method for CLI token creation via user inputs.

```APIDOC
## RefreshingToken.prompt_for_token(credentials, open_browser, to_file)

### Description
Method for CLI token creation via user inputs.

### Method
POST

### Endpoint
N/A (SDK classmethod)

### Parameters
- **credentials** (OAuthCredentials) - Required - Client credentials
- **open_browser** (bool) - Optional - Open browser to OAuth consent url automatically. (Default: `False`).
- **to_file** (Optional[str]) - Optional - Path to store/sync json version of resulting token. (Default: `None`).

### Return Type
`RefreshingToken`

### Returns
A `RefreshingToken` instance.
```

--------------------------------

### create_playlist(title: str, description: str, privacy_status: str = 'PRIVATE', video_ids: list[str] | None = None, source_playlist: str | None = None) -> str | dict[str, Any]

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Creates a new empty playlist and returns its id.

```APIDOC
## create_playlist(title: str, description: str, privacy_status: str = 'PRIVATE', video_ids: list[str] | None = None, source_playlist: str | None = None) -> str | dict[str, Any]

### Description
Creates a new empty playlist and returns its id.

### Method
create_playlist

### Parameters
- **title** (str) - Required - Playlist title
- **description** (str) - Required - Playlist description
- **privacy_status** (str) - Optional - Playlists can be `PUBLIC`, `PRIVATE`, or `UNLISTED`. Default: `PRIVATE`
- **video_ids** (Optional[list[str]]) - Optional - IDs of songs to create the playlist with
- **source_playlist** (Optional[str]) - Optional - Another playlist whose songs should be added to the new playlist

### Returns
- **str | dict[str, Any]** - ID of the YouTube playlist or full response if there was an error
```

--------------------------------

### get_album(browseId: str) -> dict[str, Any]

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Get information and tracks of an album. Returns a dictionary with album and track metadata.

```APIDOC
## get_album(browseId: str) -> dict[str, Any]

### Description
Get information and tracks of an album.

### Method
GET

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
- **browseId** (str) - Required - browseId of the album, for example returned by `search()`

### Return Type
`dict[str, Any]`

### Returns
Dictionary with album and track metadata. The result is in the following format:
```
{
  "title": "Revival",
  "type": "Album",
  "thumbnails": [],
  "description": "Revival is the...",
  "descriptionRuns": [
      {"text": "Revival is the..."},
  ],
  "artists": [
    {
      "name": "Eminem",
      "id": "UCedvOgsKFzcK3hA5taf3KoQ"
    }
  ],
  "year": "2017",
  "trackCount": 19,
  "duration": "1 hour, 17 minutes",
  "audioPlaylistId": "OLAK5uy_nMr9h2VlS-2PULNz3M3XVXQj_P3C2bqaY",
  "tracks": [
    {
      "videoId": "iKLU7z_xdYQ",
      "title": "Walk On Water (feat. Beyoncé)",
      "artists": [
        {
          "name": "Eminem",
          "id": "UCedvOgsKFzcK3hA5taf3KoQ"
        }
      ],
      "album": "Revival",
      "likeStatus": "INDIFFERENT",
      "thumbnails": null,
      "isAvailable": true,
      "isExplicit": true,
      "duration": "5:03",
      "duration_seconds": 303,
      "trackNumber": 0,
      "inLibrary": false,
      "feedbackTokens": {
        "add": "AB9zfpK...",
        "remove": "AB9zfpK..."
      },
      "pinnedToListenAgain": false,
      "listenAgainFeedbackTokens": {
        "pin": "AB9zfpJ...",
        "unpin": "AB9zfpL..."
      },
      "creditsBrowseId": "MPTCiKLU7z_xdYQ"
    }
  ],
  "other_versions": [
    {
      "title": "Revival",
      "year": "Eminem",
      "browseId": "MPREb_fefKFOTEZSp",
      "thumbnails": [...],
      "isExplicit": false
    },
  ],
  "duration_seconds": 4657
}
```

For the distinction between description and descriptionRuns, please refer to get_artist.
```

--------------------------------

### OAuthCredentials

Source: https://ytmusicapi.readthedocs.io/en/stable/index.html

OAuth credentials with client ID and secret, and methods to get authorization code, refresh token, and token from code.

```APIDOC
## OAuthCredentials

### Description
OAuth credentials with client ID and secret, and methods to get authorization code, refresh token, and token from code.

### Properties
- `client_id` - The client ID.
- `client_secret` - The client secret.

### Methods
- `get_code()` - Get an authorization code.
- `refresh_token()` - Refresh the access token.
- `token_from_code()` - Obtain a token from an authorization code.

```

--------------------------------

### ytmusicapi.helpers.initialize_context

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Initializes and returns a context dictionary.

```APIDOC
## initialize_context() -> dict[str, Any]

### Description
Initializes and returns a context dictionary.

### Returns
- **dict[str, Any]** - The initialized context dictionary.
```

--------------------------------

### get_user_videos(channelId, params)

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Retrieves a list of videos for a given user. Call this function again with the returned `params` to get the full list.

```APIDOC
## get_user_videos(channelId, params)

### Description
Retrieve a list of videos for a given user. Call this function again with the returned `params` to get the full list.

### Method
GET

### Endpoint
/user/{channelId}/videos

### Parameters
#### Path Parameters
- **channelId** (str) - Required - channelId of the user.

#### Query Parameters
- **params** (str) - Required - params obtained by `get_user()`

### Returns
- **list[dict[str, Any]]** - List of user videos
```

--------------------------------

### get_user_playlists(channelId, params)

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.mixins.html

Retrieves a list of playlists for a given user. Call this function again with the returned `params` to get the full list.

```APIDOC
## get_user_playlists(channelId, params)

### Description
Retrieve a list of playlists for a given user. Call this function again with the returned `params` to get the full list.

### Method
GET

### Endpoint
/user/{channelId}/playlists

### Parameters
#### Path Parameters
- **channelId** (str) - Required - channelId of the user.

#### Query Parameters
- **params** (str) - Required - params obtained by `get_user()`

### Returns
- **list[dict[str, Any]]** - List of user playlists in the format of `get_library_playlists()`
```

--------------------------------

### ytmusicapi.helpers.initialize_headers

Source: https://ytmusicapi.readthedocs.io/en/stable/reference/api/ytmusicapi.html

Initializes and returns a case-insensitive dictionary of headers.

```APIDOC
## initialize_headers() -> CaseInsensitiveDict[str]

### Description
Initializes and returns a case-insensitive dictionary of headers.

### Returns
- **CaseInsensitiveDict[str]** - The initialized headers dictionary.
```
Tokens:
Raw