Tunno CLI

Tunno CLI is a command-line tool for managing your personal music library. It allows you to download, organize, and manage media files efficiently with a set of user-friendly commands.

Features

• YouTube Integration: Download audio and metadata directly from YouTube videos.
• Spotify Integration: Refine metadata and ensure accurate and precise music information using Spotify's API.
• Download Playlists: Download entire playlists from YouTube.
• Image Processing: Process and enhance album covers, including images from the track, album and author whenever possible.
• Manual Spotify Search Fields: Provide optional fields to manually refine the search for metadata on Spotify (e.g., title, artist, year).
• JSON Metadata: Generate metadata files with details such as artist, album, track name,...
• Lyrics Support: Retrieve and include song lyrics along with metadata and audio files.

Installation

Prerequisites

Before using Tunno CLI, make sure you have the following installed on your system:

• Node.js: Ensure you have Node.js (version 16 or higher) installed on your system.

• yt-dlp: You need to have yt-dlp installed for downloading YouTube content. You can install it using:

  • On Linux: sudo apt install yt-dlp
  • On macOS (using Homebrew): brew install yt-dlp
  • On Windows (using Chocolatey): choco install yt-dlp

  Alternatively, you can download it from the yt-dlp GitHub page.

• ffmpeg: ffmpeg is required for audio processing. You can install it using:

  • On Linux: sudo apt install ffmpeg
  • On macOS (using Homebrew): brew install ffmpeg
  • On Windows (using Chocolatey): choco install ffmpeg

  Alternatively, you can download it from FFmpeg and follow the installation instructions.

Installation

You can install Tunno CLI directly using your preferred package manager:

Using npm:

npm install -g @tunno/cli

Using yarn:

yarn global add @tunno/cli

Using pnpm:

pnpm add -g @tunno/cli

Usage

General Commands

• Help: View available commands and usage:

  tunno -h

• Set Download Path: Define the directory for storing downloaded media:

  tunno set-path /your/custom/path

• View Current Path: Check the current download directory:

  tunno get-path

• Set API Credentials: Provide your Spotify credentials:

  tunno credentials --spotify-client-id SPOTIFY_CLIENT_ID --spotify-client-secret SPOTIFY_CLIENT_SECRET

Fast Upload

• Create Portable Bundle: Generate a portable bundle from downloaded tracks for easy import:

  tunno fast-upload

  This command scans your download directory for valid track folders and creates a timestamped zip bundle containing all tracks and a manifest file with metadata.

• Custom Output Path: Specify a custom output directory for the bundle:

  tunno fast-upload -o /path/to/output

  Example:

  tunno fast-upload -o ~/Desktop

  The bundle includes:

  • manifest.json: Metadata about all tracks (title, artists, album, thumbnails)
  • tracks/: Individual track folders with audio files, metadata, and thumbnails

YouTube Download

• Download Audio from YouTube:

  tunno youtube --id YOUR_VIDEO_ID

  Example:

  tunno youtube --id dQw4w9WgXcQ

  This command downloads the audio, processes the album cover, and generates a JSON file with metadata.

  Note: For more accurate and complete results, search directly on YouTube Music to find tracks similar to those on Spotify.

• Download Playlist from YouTube:

  tunno youtube --playlist-id YOUR_PLAYLIST_ID

  Example:

  tunno youtube --playlist-id PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI

  This command downloads all audio tracks from the specified playlist.

• Override Metadata for Spotify Search:

  You can refine the metadata used for Spotify search by providing optional fields:

  tunno youtube --id YOUR_VIDEO_ID --title "Custom Title" --artist "Custom Artist" --year 2023

  Example:

  tunno youtube --id dQw4w9WgXcQ --title "Never Gonna Give You Up" --artist "Rick Astley" --year 1987

  This command overrides the default metadata with the provided title, artist, and year.

• Basic Download:

  If you want to download only the audio without any metadata processing:

  tunno youtube --id YOUR_VIDEO_ID --basic

  Example:

  tunno youtube --id dQw4w9WgXcQ --basic

  This command downloads the audio without processing metadata or album covers.

• Metadata Control:

  You can control whether metadata and thumbnails are embedded in the audio file:

  tunno youtube --id YOUR_VIDEO_ID --add-metadata

  Example:

  tunno youtube --id dQw4w9WgXcQ --add-metadata

  This command embeds metadata and thumbnail into the audio file. By default:

  • --basic downloads include metadata (m4a format)
  • Regular downloads don't include metadata (opus format)
  • You can override this behavior with --add-metadata or --add-metadata=false

• Audio Format Control:

  You can specify the audio format using the --ext flag:

  tunno youtube --id YOUR_VIDEO_ID --ext m4a

  Example:

  tunno youtube --id dQw4w9WgXcQ --ext m4a --add-metadata

  This command downloads the audio in m4a format with embedded metadata and thumbnail.

  Supported formats: opus, m4a, mp3, flac, wav

• Basic Playlist Download:

  If you want to download only the audio from a playlist without any metadata processing:

  tunno youtube --playlist-id YOUR_PLAYLIST_ID --basic

  Example:

  tunno youtube --playlist-id PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI --basic

  This command downloads all audio tracks from the specified playlist without processing metadata or album covers.

Spotify Integration

• Refine Metadata with Spotify:

  By providing valid Spotify Client ID and Client Secret credentials with the tunno credentials command, Tunno CLI can utilize the Spotify Web API to retrieve precise music data. This enhances the accuracy of artist, album, and other metadata for the tracks you download.

  Note: If you do not use the --basic command to download only the audio, providing Spotify credentials is mandatory to obtain enhanced metadata.

Example Workflow

1. Set Path: Define the directory for downloads:

   tunno set-path /home/user/Music/Tunno

2. Set Spotify Credentials: Provide your Spotify Client ID and Client Secret:

   tunno credentials --spotify-client-id SPOTIFY_CLIENT_ID --spotify-client-secret SPOTIFY_CLIENT_SECRET

3. Download Audio: Fetch a track from YouTube:

   tunno youtube --id VIDEO_ID

Development

If you want to contribute to Tunno CLI, you can set up the development environment:

1. Clone the repository:

   git clone https://github.com/ItsLhuis/Tunno.git
   cd Tunno/apps/cli

2. Install dependencies using your preferred package manager:

   Using npm:

   npm install

   Using yarn:

   yarn install

   Using pnpm:

   pnpm install

3. Build the TypeScript project:

   Using npm:

   npm run build

   Using yarn:

   yarn build

   Using pnpm:

   pnpm build

4. For local testing, you can link the package:

   Using npm:

   npm link

   Using yarn:

   yarn global add file:$(pwd)

   Using pnpm:

   pnpm link --global

License

This project is licensed under the MIT License. See the LICENSE file for details.

Important Notice

While this tool allows you to download audio from YouTube for personal use, please be aware that downloading YouTube content may violate YouTube's Terms of Service. It is your responsibility to ensure compliance with any applicable laws or regulations. This tool is intended for personal use only, and the authors do not endorse or support using it for unauthorized purposes. Use it responsibly.