DOCSEARCHbyAlgolia
Submit Docs

ytmusicapi Documentation

repository·main·Indexed 23 days ago

https://github.com/sigma67/ytmusicapi

An unofficial Python library that emulates YouTube Music web client requests to provide programmatic access to features such as searching, library management, and playlist manipulation. It includes the YTMusic class for browsing home content, artist details, album information, and user-specific data.

Tokens
8.1K
Snippets
20
Records
87
Agent score
79%

What's inside ytmusicapi

  1. Overview of ytmusicapi Features

    main

    The ytmusicapi library provides extensive capabilities for interacting with YouTube Music:

    Browsing

    • Search (with filters) and suggestions.
    • Artist information and releases (songs, videos, albums, singles, related artists).
    • User information (videos, playlists).
    • Album and song metadata.
    • Watch playlists (next songs in radio/shuffle).
    • Song lyrics.

    Exploring Music

    • Moods and genre playlists.
    • Global and country-specific charts.

    Library Management

    • Access library contents: playlists, songs, artists, albums, subscriptions, podcasts, and channels.
    • Modify library: rate songs/albums/playlists, subscribe/unsubscribe to artists.
    • Manage play history.

    Playlists

    • Create and delete playlists.
    • Modify playlists: edit metadata, add/move/remove tracks.
    • Get playlist contents and suggestions.

    Podcasts

    • Get podcasts, episodes, channels, and episode playlists.

    Uploads

    • Upload and remove songs.
    • List uploaded songs, artists, and albums.

    Localization

    • Supports all regions and 16 languages.

  2. Set up authentication via CLI

    main

    You can use the ytmusicapi CLI to automatically generate a configuration file from your copied headers. Run the following command in your terminal and paste the headers when prompted:

    ytmusicapi browser

    MacOS Note: If your headers exceed 1024 characters, the standard terminal paste may fail. Use pbpaste to pipe your clipboard contents into the command instead:

    pbpaste | ytmusicapi browser

  3. Decompress YouTube Music FE GZIP request bodies from HAR files

    main

    YouTube Music's frontend (FE) now compresses POST request bodies using GZIP. If you need to inspect the raw JSON payload from a browser request, follow these steps:

    1. Perform the request in the YouTube Music frontend.
    2. Capture the request into a .har file using your browser's developer tools.
    3. Use the following Python script to decompress the payload. The script requires two command-line arguments: the input .har filename and the desired output filename.

    Note: The script assumes the target request is the first entry in the HAR log.

    import gzip
import json
import sys

fname = sys.argv[1]
to_save = sys.argv[2]

with open(fname, encoding='utf8') as f:
    request: dict = json.load(f)


request_body = request["log"]["entries"][0]["request"]["postData"]["text"]


raw = request_body.encode("latin1")


decompressed = gzip.decompress(raw)
with open(to_save, "w") as f:
    json.dump(json.loads(decompressed.decode("utf-8")), f, indent=2, ensure_ascii=False)

  4. Perform requests as a Brand Account

    main

    To send requests as a brand account, you do not need to change your authentication credentials. Instead, provide the brand account ID as the second argument when instantiating the YTMusic class. You can find your brand account ID in your Google Account URL (e.g., https://myaccount.google.com/b/21_digit_number).

    from ytmusicapi import YTMusic

# Pass the authentication file and the brand account ID
ytmusic = YTMusic("oauth.json", "101234161234936123473")

  6. Basic Usage of YTMusic

    main

    To use the library, import the YTMusic class. You can initialize it with an authentication file (such as oauth.json). Once initialized, you can perform tasks like creating playlists, searching for music, and adding items to playlists.

    Common operations include:

    • create_playlist(title, description): Creates a new playlist.
    • search(query): Searches for music (returns a list of results).
    • add_playlist_items(playlist_id, video_ids): Adds specific video IDs to a playlist.
    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']])

  7. Add content to your YouTube Music library

    main

    Use the following methods to manage your library content:

    • Songs: Use edit_song_library_status. Note that rate_song only adds a song to your 'Liked Songs' playlist, not your library.
    • Albums & Playlists: Use rate_playlist.
    • Artists: Use subscribe_artists to add an artist to your Subscriptions tab.
    • Podcasts: Use rate_playlist.
    • Podcast Episodes: Use add_playlist_items("SE", episode_id).

  8. Update and finalize translations

    main

    After editing your .po files (using a tool like POEdit or a manual text editor), you must run the provided shell scripts in the locales directory to synchronize and compile the translations.

    1. Update: Run ./update_po.sh to update the .po files.
    2. Finalize: Run ./update_mo.sh to generate the .mo files required by the application.
    cd locales
./update_po.sh
./update_mo.sh

  11. Get started with ytmusicapi

    main

    To begin using ytmusicapi for automating interactions with YouTube Music (such as retrieving library content, managing playlists, or uploading songs), you must first follow the setup instructions to emulate web requests.

    For detailed implementation details, refer to the setup and reference documentation.

  12. Create a new translation

    main

    To set up a new language translation, create the necessary directory structure for the target locale and copy the base template (base.pot) to a new .po file in the locale's LC_MESSAGES directory.

    # Example for English (en) and Spanish (es)
mkdir -p locales/{en,es}/LC_MESSAGES
cp locales/base.pot locales/LANG/LC_MESSAGES/base.po