Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

PyPI Build Status codecov GitHub license Python Versions


LyricsFinder is a modular and easily expandable Python Package that is used to extract lyrics from music. By having the ability to use a combination of a Google Custom Search Engine and a set of extractors for several sources, lyrics are attained with much higher accuracy and generally from the best desired source.


  • Python 3.7+ with pip

  • [Strongly Recommended]: A Google Developer API Key with the 'Custom Search' API enabled. This link should take one there once logged in.

Note: While the Google tools aren't technically required for this project, much of the beneficial functionality depends on such keys/search engines. However, direct searching/parsing from a supported URL source is possible to incorporate with this package, though not the recommended way to utilize it (unless one requires a specific application requirement/design need).

LyricsFinder uses the following packages to function:



Note that sudo may be required to install depending on your system setup. If any permission errors occur, please use the sudo flags.

The easiest way to install lyricsfinder is using pip

pip install lyricsfinder

From Source (slower/manual way):

$ git clone
$ cd LyricsFinder
$ python -m pip install .

Testing the package (optional):

You may use pytest to test the package.

Basic Usage

Since version 2.0.0 lyricsfinder is async

You can now import the package lyricsfinder as normal within your project.

import asyncio
import lyricsfinder

from aiohttp import ClientSession

async def main():
    async with ClientSession() as session:
        # you don't have to pass the ClientSession, lyricsfinder will create one for you
        # but if you call this function a lot it will improve performance
        lyrics_iterator = lyricsfinder.search_lyrics("Dusk till Dawn", api_key="<your google api key>", session=session)
        async for lyrics in lyrics_iterator:
            print(lyrics.title, lyrics.artist, lyrics.lyrics)


Some current implementations:

  • Giesela -- a unique music suite and player for Discord.

  • GiTils -- the official utilities package for Giesela, which includes an API implementation using Flask, uWSGI served through an optimized nginx webserver. The GiTils lyrics are stored in MongoDB cache. The example can be seen here.

An example of the live implementation of GiTils' lyrics blueprint from the source in action:

Lyrics are cached in MongoDB for faster loading in this implementation.

[IMPORTANT] Please note that the above live example is not for large-scale use; the public API is monitored and rate limited to prevent abuse. If you wish to host your own version, the GiTils package linked above is the implementation of the API (along with other utilities).


Please feel free to open any issues on GitHub for questions and/or support. We're happy to help!