lyric-karaoke-cli/README.md

A CLI application for displaying song lyrics in a karaoke-style format

# Lyric Karaoke CLI

A command-line application that displays song lyrics in a karaoke-style format. Search for songs by title or artist, view lyrics with animated displays, and enjoy your favorite songs right in your terminal!

[![NPM Version][npm-image]][npm-url]
[![License][license-image]][license-url]

## Features

- 🎵 Search for songs by title, artist, or both
- 🎤 Display lyrics in an animated karaoke-style format
- ⏯️ Control playback (start, pause, skip)
- 💾 Cache song data locally to minimize API requests
- 🎨 Colorful and engaging terminal interface
- 🌐 Integration with music lyrics APIs
- 📱 Cross-platform compatibility

## Installation

### Global Installation (Recommended)

```bash
npm install -g lyric-karaoke-cli
```

This will make the `lyric-karaoke` command available globally on your system.

### Local Installation

```bash
npm install lyric-karaoke-cli
```

Then you can run it with:

```bash
npx lyric-karaoke
```

## API Key Setup

This application requires an API key to fetch song data. We use the Genius Lyrics API by default.

1. Sign up for a free API key at [Genius API](https://genius.com/api-clients)
2. Create a `.env` file in your project directory
3. Add your API key to the `.env` file:

```
API_KEY=your_genius_api_key_here
```

Alternatively, you can set it as an environment variable:

```bash
export API_KEY=your_genius_api_key_here
```

## Usage

### Basic Usage

Simply run the command to launch the interactive menu:

```bash
lyric-karaoke
```

### Search for Songs

From the main menu, select "Search for a song" and enter the song title, artist, or both.

Example:
```
? Enter song title or artist: Bohemian Rhapsody Queen
```

### Controlling the Lyrics Display

When viewing lyrics, you can:
- Press `SPACE` to pause/resume
- Press `RIGHT ARROW` to skip to the next line
- Press `LEFT ARROW` to go back to the previous line
- Press `ESC` or `CTRL+C` to exit back to the menu

### Viewing Recent Songs

Select "View recent songs" from the main menu to see songs you've previously viewed. This uses the local cache to avoid additional API requests.

### Clearing the Cache

To clear the local cache:

```bash
lyric-karaoke --clear-cache
```

Or using npm:

```bash
npm run clear-cache
```

## Command Reference

```
lyric-karaoke [options]
```

Options:
- `--help` or `-h`: Display help information
- `--version` or `-v`: Display the installed version
- `--clear-cache`: Clear the local cache
- `--search="song title"`: Directly search for a song
- `--artist="artist name"`: Specify an artist when searching
- `--no-color`: Disable colored output

## Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a new branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`npm test`)
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

Please make sure your code follows the existing style and includes appropriate tests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Thanks to the Genius API for providing lyrics data
- Inspired by karaoke machines and the joy of singing along

[npm-image]: https://img.shields.io/npm/v/lyric-karaoke-cli.svg
[npm-url]: https://npmjs.org/package/lyric-karaoke-cli
[license-image]: https://img.shields.io/npm/l/lyric-karaoke-cli.svg
[license-url]: https://github.com/yourusername/lyric-karaoke-cli/blob/master/LICENSE

# Lyric Karaoke CLI

A command-line application that allows you to search for song lyrics and display them in a karaoke-style format.

## Features

- Search for songs by title, artist, or genre
- Display lyrics in a line-by-line karaoke style
- Interactive controls to start, pause, or skip sections
- Caching mechanism to minimize API calls
- Colorful and engaging terminal interface

## Installation

### Prerequisites

- Node.js (v14 or higher)
- npm (v6 or higher)

### Steps

1. Clone the repository:
   ```bash
   git clone https://github.com/your-username/lyric-karaoke-cli.git
   cd lyric-karaoke-cli
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file in the root directory (or copy the example):
   ```bash
   cp .env.example .env
   ```

4. Get an API key from [Genius API](https://genius.com/api-clients) and add it to your `.env` file:
   ```
   API_KEY=your_api_key_here
   ```

## Usage

### Running the Application

Start the application with:

```bash
npm start
```

Or run it directly with Node:

```bash
node index.js
```

### Search for Songs

1. Enter a search term (song title, artist name, or lyrics snippet)
2. Select from the search results
3. Enjoy the karaoke-style display of lyrics

### Commands

- `npm start`: Start the application
- `npm run clear-cache`: Clear the cached song data

## Configuration

You can configure the application through environment variables in the `.env` file:

| Variable | Description | Default |
|----------|-------------|---------|
| API_KEY | Your Genius API key | (required) |
| API_BASE_URL | Base URL for the API | https://api.genius.com |
| CACHE_ENABLED | Enable or disable caching | true |
| CACHE_DIRECTORY | Directory for cache storage | ./.cache |
| CACHE_TTL | Cache time-to-live in seconds | 86400 (24 hours) |
| MAX_SEARCH_RESULTS | Maximum number of search results to display | 10 |

## Development

### Project Structure

```
├── index.js                  # Main entry point
├── src/
│   ├── api/                  # API communication module
│   ├── cli/                  # Command-line interface module
│   ├── cache/                # Caching module
│   ├── utils/                # Utility functions
│   └── config.js             # Configuration module
├── .env                      # Environment variables
└── package.json              # Project metadata and dependencies
```

### Adding Features

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Commit your changes: `git commit -m 'Add some feature'`
4. Push to the branch: `git push origin feature-name`
5. Open a pull request

## License

MIT

## Acknowledgements

- [Genius API](https://genius.com/developers) for providing lyrics data
- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) for the interactive CLI
- [Chalk](https://github.com/chalk/chalk) for terminal styling