Metadata-Version: 2.4
Name: lyricy
Version: 1.5
Summary: A command line lyrics utility tool which search and add lyrics to your offline songs.
Home-page: https://github.com/yogeshwaran01/lyricy
Download-URL: https://github.com/yogeshwaran01/lyricy/archive/master.zip
Author: Yogeshwaran R
Author-email: yogeshin247@gmail.com
License: MIT
Keywords: python package lyrics lrc yogeshwaran01 songs
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: certifi>=2024.2.2
Requires-Dist: charset-normalizer>=3.3.2
Requires-Dist: click>=8.1.7
Requires-Dist: idna>=3.6
Requires-Dist: music-tag>=0.4.3
Requires-Dist: mutagen>=1.47.0
Requires-Dist: Pygments>=2.17.2
Requires-Dist: pylrc>=0.1.2
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.1
Requires-Dist: soupsieve>=2.5
Requires-Dist: urllib3>=2.2.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

<!-- headings -->

<h1 align="center"> 🎼 lyricy </h1>

<p align="center">A command line lyrics utility tool which search and add lyrics to your offline songs.</p>

<!-- Badges -->

<p align="center">
    <a href="https://pypi.org/project/lyricy/">
    <img alt="PyPi" src="https://img.shields.io/pypi/v/lyricy.svg"/>
    </a>
    <a href="https://pepy.tech/project/lyricy">
    <img alt="Downloads" src="https://pepy.tech/badge/lyricy"/>
    </a>
    <a href="https://github.com/yogeshwaran01/lyricy/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/yogeshwaran01/lyricy"></a>
    <a href="https://github.com/yogeshwaran01/lyricy/network">
    <img alt="GitHub forks" src="https://img.shields.io/github/forks/yogeshwaran01/lyricy"></a>
    <a href="https://github.com/yogeshwaran01/lyricy/blob/master/LICENSE.txt">
    <img alt="GitHub license" src="https://img.shields.io/github/license/yogeshwaran01/lyricy?color=blue"/>
    </a>
    <a href="https://github.com/psf/black">
    <img alt="Code style" src="https://img.shields.io/badge/codestyle-Black-blue"/>
    </a>
    <img alt="GitHub Repo size" src="https://img.shields.io/github/repo-size/yogeshwaran01/lyricy"/>
    <a href="https://github.com/yogeshwaran01/lyricy/actions/workflows/python-publish.yml">
    <img alt="Upload lyricy to pypi" src="https://github.com/yogeshwaran01/lyricy/actions/workflows/python-publish.yml/badge.svg"/>
    </a>
    <a href="https://github.com/yogeshwaran01/lyricy/actions/workflows/python-package.yml">
    <img alt="Python package" src="https://github.com/yogeshwaran01/lyricy/actions/workflows/python-package.yml/badge.svg"/>
    </a>
</p>

</hr>

## Why lyricy ?

We can use [spotDL/spotify-downloader](https://github.com/spotDL/spotify-downloader) to download our spotify playlist and songs along with album art and metadata. But it does not add the lyrics of the songs in song metadata. lyricy search for the lyrics of the song add to song metadata.

you can use [Retro music player](https://github.com/RetroMusicPlayer/RetroMusicPlayer) for android to listen the offline local songs with synced lyrics.

## Features

- Used as a Python package and Command Line Interface (CLI)
- Easy to add lyrics to your offline songs
- Preview of lyrics
- Synced lyrics with lrc time tags
- Lyrics without lrc tags
- Save lyrics as lrc file
- Add your own lyrics or downloaded lyrics to songs

## Usage

- [Using as a CLI tool](#cli)
- [Using as a python package](#python-package)

### CLI

#### Installation

Using pip

```bash
pip install lyricy
```

Windows user download this [executable file](https://github.com/yogeshwaran01/lyricy/releases/download/1.2/lyricy.exe)

![demo](https://github.com/yogeshwaran01/lyricy/blob/master/demo/demo_lyricy.gif?raw=true)

```txt
Usage: python -m lyricy [OPTIONS] COMMAND [ARGS]...

  A command line lyrics utility tool which search and add lyrics to your
  offline songs.

Options:
  --help  Show this message and exit.

Commands:
  add     Search and add lyrics to given TRACK.
  remove  Remove lyrics from given TRACK.
  search  Search for lyrics for given track or query
  show    Show the lyrics of TRACK if available.
```

- [Searching for lyrics using your queries](#searching-for-lyrics-using-your-queries)
- [Searching for lyrics for your track](#searching-for-lyrics-for-your-track)
- [Adding lyrics](#adding-lyrics)
- [Remove lyrics](#remove-lyrics)
- [Changing lyrics provider](#changing-lyrics-provider)
- [Show lyrics](#show-lyrics)
- [Downloading lrc file](#downloading-lrc-file)
- [Add lrc file to song](#add-lrc-file-to-song)

#### Searching for lyrics using your queries

```txt
Usage: python -m lyricy search [OPTIONS]

  Search for lyrics for given track or query

Options:
  -t, --track PATH       file path of track
  -d, --disable-preview  Disable the preview
  -l, --only-lyrics      Show Lyrics Only (without LRC tag)
  -s, --save TEXT        Save file as .lrc
  -q, --query TEXT       search query of track name
  -p, --provider TEXT    Lyrics provider name [rc] or [mo]
  --help                 Show this message and exit.
```

```bash
lyricy search --query "jolly yo gymkanna"
```

#### Searching for lyrics for your track

Track must have album metadata `title`

```bash
lyricy search --track 'Imagine Dragons - Believer.mp3'
```

After searching it print list of lyrics, enter the index number lyrics to get the full lyrics

#### Adding lyrics

Adding lyrics to track metadata to get synced lyrics

```txt
Usage: python -m lyricy add [OPTIONS] TRACK

  Search and add lyrics to given TRACK.

  TRACK can be the filepath of a track or a directory path.

Options:
  -q, --query TEXT       search for this query instead of track name
  -d, --disable-preview  Disable the preview
  --show                 Print the lyrics and ask for confirmation
  --lrc PATH             Lyrics file to add on track
  -p, --provider TEXT    Lyrics provider name: [lr] (LRCLIB), [bl] (BetterLyrics), [rc] (RcLyricsBand), or [mo] (Megalobiz)
  -r, --recursive        Recursively process directories
  -a, --auto             Auto-match and save lyrics without prompting
  --help                 Show this message and exit.
```

```bash
lyricy add 'Imagine Dragons - Believer.mp3'
```

Select the preferred lyrics for the song to add it.

If the track does not have metadata `title` or has an irrelevant filename, you can use the `--query` option to override this:

```bash
lyricy add 'some-track.mp3' --query "vikram title track"
```

#### Flagship Automation (Bulk Tagging & Auto-Match)

You can recursively tag an entire directory of tracks and automatically match/save lyrics using the default smart fallback chain without any interactive prompting:

```bash
lyricy add --recursive --auto ./my_music_directory/
```

#### Changing lyrics provider

By default, the lyrics provider uses a smart fallback chain starting with **LRCLIB** (our flagship premium provider). You can manually lock it to a specific provider:

- `lr` for [https://lrclib.net](https://lrclib.net) (Default, lightning-fast, high-quality synchronized/plain lyrics)
- `bl` for [BetterLyrics](https://lyrics-api.boidu.dev) (Direct timed XML TTML parsing)
- `rc` for [https://rclyricsband.com/](https://rclyricsband.com/) (Scraped synchronized lyrics)
- `mo` for [https://www.megalobiz.com/](https://www.megalobiz.com/) (Scraped synchronized lyrics)

```bash
lyricy add 'some-track.mp3' --query "vikram title track" --provider bl
```

```bash
lyricy search --query "karka kark" --provider lr
```

#### Remove lyrics

```txt
Usage: lyricy remove [OPTIONS] TRACK

  Remove lyrics from given TRACK.

  TRACK is the filepath of track.

Options:
  --help  Show this message and exit.
```

```bash
lyricy remove 'Imagine Dragons - Believer.mp3'
```

#### Show lyrics

```txt
Usage: lyricy show [OPTIONS] TRACK

  Show the lyrics of TRACK if available.

  TRACK is the filepath of track.

Options:
  -l, --only-lyrics  Show Lyrics Only (without LRC tag)
  --help             Show this message and exit.
```

```bash
lyricy show 'Imagine Dragons - Believer.mp31
```

#### Downloading lrc file

```bash
lyricy search --query "new york" --save "new_york"
```

This search and ask for the prompt, select any song it will download and save as `lrc` file

#### Add lrc file to song

```bash
lyricy add track.mp3 --lrc track.lrc
```

It will add the lyrics to song metadata

### Python Package

#### Install

Using pip

```bash
pip install lyricy
```

#### Simple Usage

```python
>>> from lyricy import Lyricy

>>> l = Lyricy()
>>> results = l.search("karka karka")
>>> selected_lyrics = results[0]
>>> selected_lyrics.fetch()

>>> selected_lyrics.lyrics
>>> selected_lyrics.lyrics_without_lrc_tags

```

#### Saving and adding lyrics to track

```python
>>> selected_lyrics.save("lyrics.lrc")
>>> selected_lyrics.add_to_track("path_to_track.mp3")
```

#### Using Other Providers

By default, the provider is **LRCLIB** (`Providers.LRCLIB`), but you can specify other providers like `Providers.BETTERLYRICS`, `Providers.RCLYRICSBAND`, or `Providers.MEGALOBIZ`.

```python
>>> from lyricy import Lyricy, Providers

>>> l = Lyricy()
>>> results = l.search("vikram", provider=Providers.BETTERLYRICS)
>>> selected_lyrics = results[0]
>>> selected_lyrics.fetch()

>>> selected_lyrics.lyrics
>>> selected_lyrics.lyrics_without_lrc_tags
```

## Dev Setup

- Clone repo
- Install package requirements

```bash
pip install -r requirements
```

- Install dev requiremnts

```bash
pip install black flake8 pytest
```

- Linting

```bash
black
flake8 -v
```

- Test

```bash
pytest -v
```

## Lyrics Providers

- **LRCLIB** ([https://lrclib.net](https://lrclib.net)) - Lightning-fast default provider.
- **BetterLyrics** ([https://lyrics-api.boidu.dev](https://lyrics-api.boidu.dev)) - Timed XML TTML.
- **RcLyricsBand** ([https://rclyricsband.com/](https://rclyricsband.com/)) - Scraped synced lyrics.
- **Megalobiz** ([https://www.megalobiz.com/](https://www.megalobiz.com/)) - Scraped synced lyrics.

## Contributions

Contributions are Welcome. Feel free to report bugs in issue and fix some bugs by creating pull requests. Comments, Suggestions, Improvements and Enhancements are always welcome.
