# LyricsGenius: a Python client for the Genius.com API
[](https://travis-ci.org/johnwmillr/LyricsGenius)
[](https://lyricsgenius.readthedocs.io/en/latest/?badge=master)
[](https://pypi.org/project/lyricsgenius/)
[](https://pypi.org/project/lyricsgenius/)
`lyricsgenius` provides a simple interface to the song, artist, and lyrics data stored on [Genius.com](https://www.genius.com).
The full documentation for `lyricsgenius` is available online at [Read the Docs](https://lyricsgenius.readthedocs.io/en/master/).
## Setup
Before using this package you'll need to sign up for a (free) account that authorizes access to [the Genius API](http://genius.com/api-clients). The Genius account provides a `access_token` that is required by the package. See the [Usage section](https://github.com/johnwmillr/LyricsGenius#usage) below for examples.
## Installation
`lyricsgenius` requires Python 3.
Use `pip` to install the package from PyPI:
```bash
pip install lyricsgenius
```
Or, install the latest version of the package from GitHub:
```bash
pip install git+https://github.com/johnwmillr/LyricsGenius.git
```
## Usage
Import the package and initiate Genius:
```python
import lyricsgenius
genius = lyricsgenius.Genius(token)
```
If you don't pass a token to the `Genius` class, `lyricsgenus` will look for an environment variable called `GENIUS_ACCESS_TOKEN` and attempt to use that for authentication.
```python
genius = Genius()
```
Search for songs by a given artist:
```python
artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title")
print(artist.songs)
```
By default, the `search_artist()` only returns songs where the given artist is the primary artist.
However, there may be instances where it is desirable to get all of the songs that the artist appears on.
You can do this by setting the `include_features` argument to `True`.
```python
artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title", include_features=True)
print(artist.songs)
```
Search for a single song by the same artist:
```python
song = artist.song("To You")
# or:
# song = genius.search_song("To You", artist.name)
print(song.lyrics)
```
Add the song to the artist object:
```python
artist.add_song(song)
# the Artist object also accepts song names:
# artist.add_song("To You")
```
Save the artist's songs to a JSON file:
```python
artist.save_lyrics()
```
Searching for an album and saving it:
```python
album = genius.search_album("The Party", "Andy Shauf")
album.save_lyrics()
```
There are various options configurable as parameters within the `Genius` class:
```python
genius.verbose = False # Turn off status messages
genius.remove_section_headers = True # Remove section headers (e.g. [Chorus]) from lyrics when searching
genius.skip_non_songs = False # Include hits thought to be non-songs (e.g. track lists)
genius.excluded_terms = ["(Remix)", "(Live)"] # Exclude songs with these words in their title
```
You can also call the package from the command line:
```bash
export GENIUS_ACCESS_TOKEN="my_access_token_here"
python3 -m lyricsgenius --help
```
Search for and save lyrics to a given song and album:
```bash
python3 -m lyricsgenius song "Begin Again" "Andy Shauf" --save
python3 -m lyricsgenius album "The Party" "Andy Shauf" --save
```
Search for five songs by 'The Beatles' and save the lyrics:
```bash
python3 -m lyricsgenius artist "The Beatles" --max-songs 5 --save
```
## Example projects
- [Trucks and Beer: A textual analysis of popular country music](http://www.johnwmillr.com/trucks-and-beer/)
- [Neural machine translation: Explaining the Meaning Behind Lyrics](https://github.com/tsandefer/dsi_capstone_3)
- [What makes some blink-182 songs more popular than others?](http://jdaytn.com/posts/download-blink-182-data/)
- [Sentiment analysis on hip-hop lyrics](https://github.com/Hugo-Nattagh/2017-Hip-Hop)
- [Does Country Music Drink More Than Other Genres?](https://towardsdatascience.com/does-country-music-drink-more-than-other-genres-a21db901940b)
- [49 Years of Lyrics: Why So Angry?](https://towardsdatascience.com/49-years-of-lyrics-why-so-angry-1adf0a3fa2b4)
## Contributing
Please contribute! If you want to fix a bug, suggest improvements, or add new features to the project, just [open an issue](https://github.com/johnwmillr/LyricsGenius/issues) or send me a pull request.
Raw data
{
"_id": null,
"home_page": "https://github.com/johnwmillr/lyricsgenius",
"name": "lyricsgenius",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "genius api genius-api music lyrics artists albums songs",
"author": "John W. Miller",
"author_email": "john.w.millr+lg@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/69/de/a6ff1634e599cf147b3a4b84e2416fc37afeb840e9a5aa88fe32491fab13/lyricsgenius-3.0.1.tar.gz",
"platform": "",
"description": "# LyricsGenius: a Python client for the Genius.com API\n[](https://travis-ci.org/johnwmillr/LyricsGenius)\n[](https://lyricsgenius.readthedocs.io/en/latest/?badge=master)\n[](https://pypi.org/project/lyricsgenius/)\n[](https://pypi.org/project/lyricsgenius/)\n\n`lyricsgenius` provides a simple interface to the song, artist, and lyrics data stored on [Genius.com](https://www.genius.com).\n\nThe full documentation for `lyricsgenius` is available online at [Read the Docs](https://lyricsgenius.readthedocs.io/en/master/).\n\n## Setup\nBefore using this package you'll need to sign up for a (free) account that authorizes access to [the Genius API](http://genius.com/api-clients). The Genius account provides a `access_token` that is required by the package. See the [Usage section](https://github.com/johnwmillr/LyricsGenius#usage) below for examples.\n\n## Installation\n`lyricsgenius` requires Python 3.\n\nUse `pip` to install the package from PyPI:\n\n```bash\npip install lyricsgenius\n```\n\nOr, install the latest version of the package from GitHub:\n\n```bash\npip install git+https://github.com/johnwmillr/LyricsGenius.git\n```\n\n## Usage\nImport the package and initiate Genius:\n\n```python\nimport lyricsgenius\ngenius = lyricsgenius.Genius(token)\n```\n\nIf you don't pass a token to the `Genius` class, `lyricsgenus` will look for an environment variable called `GENIUS_ACCESS_TOKEN` and attempt to use that for authentication.\n\n```python\ngenius = Genius()\n```\n\nSearch for songs by a given artist:\n\n```python\nartist = genius.search_artist(\"Andy Shauf\", max_songs=3, sort=\"title\")\nprint(artist.songs)\n```\nBy default, the `search_artist()` only returns songs where the given artist is the primary artist.\nHowever, there may be instances where it is desirable to get all of the songs that the artist appears on.\nYou can do this by setting the `include_features` argument to `True`.\n\n```python\nartist = genius.search_artist(\"Andy Shauf\", max_songs=3, sort=\"title\", include_features=True)\nprint(artist.songs)\n```\n\nSearch for a single song by the same artist:\n\n```python\nsong = artist.song(\"To You\")\n# or:\n# song = genius.search_song(\"To You\", artist.name)\nprint(song.lyrics)\n```\n\nAdd the song to the artist object:\n\n```python\nartist.add_song(song)\n# the Artist object also accepts song names:\n# artist.add_song(\"To You\")\n```\n\nSave the artist's songs to a JSON file:\n\n```python\nartist.save_lyrics()\n```\n\nSearching for an album and saving it:\n\n```python\nalbum = genius.search_album(\"The Party\", \"Andy Shauf\")\nalbum.save_lyrics()\n```\n\nThere are various options configurable as parameters within the `Genius` class:\n\n```python\ngenius.verbose = False # Turn off status messages\ngenius.remove_section_headers = True # Remove section headers (e.g. [Chorus]) from lyrics when searching\ngenius.skip_non_songs = False # Include hits thought to be non-songs (e.g. track lists)\ngenius.excluded_terms = [\"(Remix)\", \"(Live)\"] # Exclude songs with these words in their title\n```\n\nYou can also call the package from the command line:\n\n```bash\nexport GENIUS_ACCESS_TOKEN=\"my_access_token_here\"\npython3 -m lyricsgenius --help\n```\n\nSearch for and save lyrics to a given song and album:\n\n```bash\npython3 -m lyricsgenius song \"Begin Again\" \"Andy Shauf\" --save\npython3 -m lyricsgenius album \"The Party\" \"Andy Shauf\" --save\n```\n\nSearch for five songs by 'The Beatles' and save the lyrics:\n\n```bash\npython3 -m lyricsgenius artist \"The Beatles\" --max-songs 5 --save\n```\n\n## Example projects\n\n - [Trucks and Beer: A textual analysis of popular country music](http://www.johnwmillr.com/trucks-and-beer/)\n - [Neural machine translation: Explaining the Meaning Behind Lyrics](https://github.com/tsandefer/dsi_capstone_3)\n - [What makes some blink-182 songs more popular than others?](http://jdaytn.com/posts/download-blink-182-data/)\n - [Sentiment analysis on hip-hop lyrics](https://github.com/Hugo-Nattagh/2017-Hip-Hop)\n - [Does Country Music Drink More Than Other Genres?](https://towardsdatascience.com/does-country-music-drink-more-than-other-genres-a21db901940b)\n - [49 Years of Lyrics: Why So Angry?](https://towardsdatascience.com/49-years-of-lyrics-why-so-angry-1adf0a3fa2b4)\n\n## Contributing\nPlease contribute! If you want to fix a bug, suggest improvements, or add new features to the project, just [open an issue](https://github.com/johnwmillr/LyricsGenius/issues) or send me a pull request.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Download lyrics and metadata from Genius.com",
"version": "3.0.1",
"split_keywords": [
"genius",
"api",
"genius-api",
"music",
"lyrics",
"artists",
"albums",
"songs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d32be32f6922f70fd1b9900b50b228f6585cd60a96bdf03589df738f627d388",
"md5": "8a47cb4ea9a529e4085001a9a9f3c29f",
"sha256": "145df7d79e6b6ebe7ff6da9ed08c0cb43b251bb88f859339224b20e3f8399b05"
},
"downloads": -1,
"filename": "lyricsgenius-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8a47cb4ea9a529e4085001a9a9f3c29f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 59419,
"upload_time": "2021-04-18T15:17:58",
"upload_time_iso_8601": "2021-04-18T15:17:58.064840Z",
"url": "https://files.pythonhosted.org/packages/0d/32/be32f6922f70fd1b9900b50b228f6585cd60a96bdf03589df738f627d388/lyricsgenius-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69dea6ff1634e599cf147b3a4b84e2416fc37afeb840e9a5aa88fe32491fab13",
"md5": "1d9eb44f441be2b38f7fe09678c93e6c",
"sha256": "83aef55ffca0b8ea69651c4b144693d1c012687a7da57f88d095b333f2e18928"
},
"downloads": -1,
"filename": "lyricsgenius-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1d9eb44f441be2b38f7fe09678c93e6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32968,
"upload_time": "2021-04-18T15:18:00",
"upload_time_iso_8601": "2021-04-18T15:18:00.004480Z",
"url": "https://files.pythonhosted.org/packages/69/de/a6ff1634e599cf147b3a4b84e2416fc37afeb840e9a5aa88fe32491fab13/lyricsgenius-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-18 15:18:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "johnwmillr",
"github_project": "lyricsgenius",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "lyricsgenius"
}
JSON
