lyricsgenius

The LyricsGenius documentation is organized into several key modules for interacting with the Genius.com API:

• API and PublicAPI classes: Core interfaces for interacting with the service.
• OAuth2 class: Handles authentication via OAuth2.
• Genius class: The primary client class used to interact with the Genius API.
• Request sender: The underlying mechanism for dispatching requests.
• Types: Definitions of the data structures returned by the API.
• Utility functions: Helper functions for common tasks.

To use lyricsgenius, you must first obtain an access token from Genius.com.

1. Sign up for a free account at Genius.
2. Navigate to the API Clients page.
3. Create a new API client.
4. Generate an access token.

Genius provides two types of tokens:

• client access token: Recommended for most use cases. Use this to retrieve song lyrics and song information. It does not require user authentication via OAuth2. You can generate this by clicking Generate Access Token on the API Clients page.
• user token: Used for advanced features like managing annotations or accessing specific user account information. If you are building a website that uses the Genius Web Annotator, you will need this. lyricsgenius provides an auth class to assist with user authentication.

To authenticate a third-party user, use the OAuth2 class to generate a redirect URL. After the user completes the flow at the redirect URI, capture the code and state from the request parameters and pass them to auth.get_user_token(code, state) to obtain the token.

from lyricsgenius import OAuth2, Genius

# 1. Initialize auth (Full code exchange example)
auth = OAuth2.full_code_exchange(
    'my_client_id',
    'my_redirect_uri',
    'my_client_secret',
    scope='all',
    state='some_unique_value'
)

# 2. Get the URL to redirect the user to
url_for_user = auth.url
print('Redirecting you to ' + url_for_user)

# 3. After user redirects back, get token from request params
# (Example using Flask-like logic)
code = request.args.get('code')
state = request.args.get('state')
token = auth.get_user_token(code, state)

genius = Genius(token)

LyricsGenius supports two OAuth2 flows via the OAuth2 class:

1. Client-only app (OAuth2.client_only_app): Requires client_id, redirect_uri, and optionally scope.
2. Full code exchange (OAuth2.full_code_exchange): Requires client_id, redirect_uri, client_secret, scope, and state.

Environment Variables

You can use lyricsgenius.auth_from_environment() to load credentials from these environment variables:

• GENIUS_CLIENT_ID
• GENIUS_REDIRECT_URI
• GENIUS_CLIENT_SECRET

import lyricsgenius as lg

# Load from environment
client_id, redirect_uri, client_secret = lg.auth_from_environment() 

# Example: Client-only app flow for self-authentication
from lyricsgenius import OAuth2, Genius

auth = OAuth2.client_only_app(
    'my_client_id',
    'my_redirect_uri',
    scope='all'
)

token = auth.prompt_user()
genius = Genius(token)

To use the library, import lyricsgenius and instantiate the Genius class. You must provide an access_token obtained from the Genius API.

If you do not pass a token explicitly, the library will automatically look for an environment variable named GENIUS_ACCESS_TOKEN.

import lyricsgenius

# Using an explicit token
genius = lyricsgenius.Genius(token)

# Using the GENIUS_ACCESS_TOKEN environment variable
genius = lyricsgenius.Genius()

You can install the lyricsgenius library using pip to access the Genius.com API and download song lyrics.

pip install lyricsgenius

lyricsgenius requires Python 3. You can install the package from PyPI using pip.

pip install lyricsgenius