<div align="center">

<img width="128" height="128" alt="Gharmonize Logo" src="https://github.com/user-attachments/assets/adf9d2f8-a99b-43c8-9c37-d4a47f5b1e3f" />

Gharmonize

https://github.com/user-attachments/assets/94f23b28-afae-4d42-ada4-783ecfb321dc

Download • Convert • Rip • Tag — with a Web UI + Desktop builds (AppImage/EXE)

Fast, modular media processing powered by yt-dlp and ffmpeg: downloads from YouTube/YouTube Music and supported platforms (X, Facebook, Instagram, Vimeo, Dailymotion, TikTok), Spotify-based metadata matching, DRM-free disc ripping, and GPU-accelerated conversions — all driven by a reliable job engine.

Spotify note: Spotify is used for metadata + matching (track/playlist/album info). Gharmonize does not claim DRM bypass.

<img width="1666" height="899" alt="ss" src="https://github.com/user-attachments/assets/449c5f67-4240-4ca0-8da4-b2ca97a3b5bb" /> </div>

---

⚡ Quick Start

Docker Compose (recommended)

git clone https://github.com/G-grbz/Gharmonize
cd Gharmonize

# prepare folders (default: /opt/gharmonize)
sudo mkdir -p /opt/gharmonize/{uploads,outputs,temp,cookies,local-inputs}
sudo touch /opt/gharmonize/.env /opt/gharmonize/cookies/cookies.txt
sudo chmod -R a+rw /opt/gharmonize

# set at least ADMIN_PASSWORD + APP_SECRET in /opt/gharmonize/.env
# start
docker compose up -d --build

Open:

• http://localhost:5174

Local (Node & npm)

git clone https://github.com/G-grbz/Gharmonize
cd Gharmonize

# Linux
BUILD_ELECTRON=1 npm i
npm start

---

✅ What you get (at a glance)

• YouTube / YouTube Music downloads (single, playlist, mixes) via yt-dlp
• X (Twitter) / Facebook / Instagram / Vimeo / Dailymotion / TikTok support (download/convert flows)
• Spotify & Apple Music integration for metadata + mapping to YouTube (track / playlist / album)
• Audio & video conversion powered by ffmpeg, with reliability-first presets
• Fix A/V sync issues using FPS adjustment presets for AC3 / EAC3 / AAC
• GPU acceleration for local video transcoding: NVENC, VAAPI, Intel QSV
• Disc ripping (DRM-free only) using ffmpeg + MKVToolNix, with stream selection in Web UI
• Job engine for batch processing, progress, and reliability

---

📘 Table of Contents

• Overview
• Features
• Requirements
• Quick Start (Local – Node & npm)
• Quick Start (Docker Compose)
• Docker vs Local Usage Notes
• Environment Variables (.env)
• Gharmonize Homepage Widget
• Notes & Troubleshooting
• License
• Third-Party Licenses

---

Overview

Gharmonize is a media automation toolkit running as a Node.js server with an optional Electron desktop shell. It bundles multiple third‑party utilities (FFmpeg, MKVToolNix, yt-dlp, deno etc.) to provide:

• High‑reliability downloading
• Disc/media processing
• Transcoding with GPU acceleration
• Smart metadata extraction and automatic tagging

License details are available in Third-Party Licenses and LICENSES.md.

---

Features

YouTube & YouTube Music

• yt-dlp integration with SABR / 403 workarounds
• Support for single videos, playlists, and mixes
• Customizable yt-dlp arguments via environment variables

Social Platforms

• Support for:

  • X (Twitter)
  • Facebook
  • Instagram
  • Vimeo
  • Dailymotion
  • TikTok

Spotify Integration

• Spotify Web API support (track / playlist / album)
• Automatic mapping from Spotify items to YouTube
• Optional preference for Spotify metadata when tagging

Disc Ripping (DRM-free only)

• Rip non-DRM optical discs (e.g., DVD/Blu-ray) into audio/video files
• Uses ffmpeg and MKVToolNix tools under the hood
• Disc analysis and stream selection via the web UI

Audio & Video Conversion

• ffmpeg-based conversion with focus on reliability

• Convert to mp3 / flac / wav / ogg, or pass through mp4 without re-encoding when possible

• Ready-made FPS adjustment presets for AC3 / EAC3 / AAC audio to fix or prevent sync issues

• Transcode arbitrary local video files with hardware acceleration:

  • NVIDIA NVENC
  • VAAPI
  • Intel Quick Sync (QSV)

• Local & Uploaded Media

  • File uploads handled via Multer
  • Optional local media directory (LOCAL_INPUT_DIR) for selecting files without uploading
  • Admin-only access for local inputs

• Deployment & Config

  • Docker image & Docker Compose setup
  • Settings API for runtime configuration from the UI
  • Electron builds for Windows/Linux
  • .env-driven configuration for server, YouTube, Spotify and processing behavior

---

Requirements

| Requirement | Version | Description | | ---------------- | -------- | ------------------------ | | Node.js | >= 20 | Required | | ffmpeg | Any | Included in Docker | | yt-dlp | Latest | Included in Docker | | Spotify API Keys | Optional | Enables Spotify metadata |

---

Quick Start (Local – Node & npm)

1. Clone the Repository and Enter the Directory

git clone https://github.com/G-grbz/Gharmonize
cd Gharmonize

2. Create the .env File

To enable UI configuration, fill in ADMIN_PASSWORD and APP_SECRET. You can generate a secure APP_SECRET using the following command:

openssl rand -hex 32

---

3. Installation Commands

Linux

BUILD_ELECTRON=1 npm i

Windows (CMD)

set BUILD_ELECTRON=1
npm i

---

Default .env Locations (AppImage or .exe only)

These paths are not general application directories. They are created automatically only when running AppImage or Windows .exe builds, and store the default-generated .env file:

• Windows: %appdata%\Gharmonize
• Linux: ~/.config/Gharmonize/
• Default Password: 123456

You can edit environment variables in the Settings panel. Windows users should add the file paths for ffmpeg and yt-dlp to their environment variables.

---

Run Without Building

To run the application without building:

Optional: If you do not want to use ffmpeg, ffprobe, yt-dlp, and mkvmerge tools from your host system — or if you prefer using the tested, verified versions — you can run:

npm run download:binaries

This command downloads the required third‑party binaries into the app directory so the application can use them internally.

Note: While this step is optional when using Run Without Building (npm start), it is strongly recommended for AppImage and Windows .exe builds to ensure consistent, validated binary versions.

Important: If you use npm run download:binaries, you must remove or clear any manually set binary paths in your .env file (FFMPEG_PATH, FFPROBE_PATH, YTDLP_PATH, etc.). Otherwise, the app will try to use the system tools instead of the downloaded ones.

npm start

---

Build Commands

Build AppImage (Linux only):

npm run desktop:build:appimage

Build NSIS (Windows Installer):

npm run desktop:build:nsis

Note: If you choose Install for all users (which installs under Program Files), you must manually create the temp, outputs, and uploads folders inside the installation directory and grant read/write permissions.

Alternatively, install to a custom directory outside Program Files or Program Files (x86).

Build Portable (Windows standalone):

npm run desktop:build:portable

Build both Windows versions (NSIS + Portable):

npm run desktop:build:all

---

Quick Start (Docker Compose)

1. Clone the Repository and Enter the Directory

git clone https://github.com/G-grbz/Gharmonize
cd Gharmonize

2. Create Required Folders and Files

The commands below assume the default directory /opt/gharmonize. If you want to use a different one, update the paths in the commands and under the volumes: section of your docker-compose.yml file. You can also switch the Docker image branch to either latest or testing if you prefer.

sudo mkdir -p /opt/gharmonize/{uploads,outputs,temp,cookies}
sudo touch /opt/gharmonize/.env /opt/gharmonize/cookies/cookies.txt
sudo chmod -R a+rw /opt/gharmonize

3. Configure Environment Variables

In the .env file, you only need to set ADMIN_PASSWORD and APP_SECRET. All other settings can be adjusted later via the settings panel.

To generate a random APP_SECRET:

openssl rand -hex 32

⚡ Optional: Enable NVIDIA NVENC (hardware-accelerated video encoding)

If you have an NVIDIA GPU and want to use hardware-accelerated encoding (NVENC) inside the container:

1. Install the proprietary NVIDIA driver on the host.
2. Install the NVIDIA Container Toolkit so Docker can access your GPU.
3. Update your docker-compose.yml service like this:

version: "3.9"
services:
  web:
    image: ggrbz/gharmonize:latest
    container_name: Gharmonize
    user: "${PUID:-1000}:${PGID:-1000}"
    # Enable access to the NVIDIA GPU
    gpus: all
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility
      - NODE_ENV=production
      - PORT=${PORT:-5174}
      - YT_FORCE_IPV4=1
      - YT_APPLY_403_WORKAROUNDS=1
      - YTDLP_EXTRA=--force-ipv4
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - DATA_DIR=/usr/src/app
    ports:
      - "${PORT:-5174}:${PORT:-5174}"
    volumes:
      - /opt/gharmonize/uploads:/usr/src/app/uploads
      - /opt/gharmonize/outputs:/usr/src/app/outputs
      - /opt/gharmonize/temp:/usr/src/app/temp
      - /opt/gharm