yt-cli-terminal 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ping-Phantom39
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,442 @@
+# ⚡ YouTube Terminal Suite (yt-song-cli)
+[![SS of yt-player engine](demo.png)](https://youtu.be/aq0VeB1LSt8?si=epWLrQFFAEb2CtD4)
+
+
+[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go)](https://golang.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![Platform Support](https://img.shields.io/badge/platform-linux%20%7C%20macos-lightgrey?style=flat-square)](https://github.com/Ping-Phantom39/yt-cli)
+[![Built with Bubble Tea](https://img.shields.io/badge/built%20with-Bubble%20Tea-magenta?style=flat-square)](https://github.com/charmbracelet/bubbletea)
+
+## 🖥️ Supported Operating Systems
+
+The tools are written in Go and rely on native audio/video back‑ends. They have been tested and are officially supported on:
+
+- **Linux** (Ubuntu, Debian, Fedora, etc.) – requires ALSA/PulseAudio/pipewire libraries.
+- **macOS** – uses CoreAudio via the `beep` library.
+- **Windows** – builds with CGO and uses WASAPI; however the current CI and packaging focus on Linux/macOS.
+
+For other platforms you may need to install the required audio/video dependencies manually.
+
+Welcome to the **YouTube Terminal Suite** (`yt-song-cli`), a professional monorepo housing two high-performance, keyboard-driven Go CLI applications styled with a sleek cyberpunk aesthetic. The suite features a video streaming player (`ytplayer`) and an offline audio player/downloader (`ytmusic`), providing the ultimate terminal-native YouTube media experience.
+
+---
+
+## 🧭 Monorepo Overview
+
+This repository contains two decoupled, highly modular Go utilities:
+
+| Component | Target Directory | Binary Name | Description | Key Technologies |
+|---|---|---|---|---|
+| **Video Client** | [`/yt-player`](yt-player) | `ytplayer` | Cyberpunk terminal video searcher, downloader, and mpv-backed streaming player. | `yt-dlp`, Bubble Tea, `mpv` |
+| **Audio Client** | [`/yt-song`](yt-song) | `ytmusic` | Highly optimized music player with low-level audio streaming and local MP3 caching. | `yt-dlp`, Bubble Tea, `gopxl/beep` |
+
+---
+
+## 🎨 System Architecture
+
+The following diagram illustrates how the CLI tools leverage standard Go layouts and external binaries for media scraping, multiplexing, transcoding, and low-level playback:
+
+
+```mermaid
+graph TD
+    subgraph Monorepo["yt-song-cli Workspace"]
+        direction TB
+        subgraph YTPlayer["ytplayer (Video Client)"]
+            VP_Cmd["Cobra CLI Bootstrapper"] --> VP_UI["Bubble Tea UI"]
+            VP_UI --> VP_DL["Downloader Engine"]
+            VP_UI --> VP_Exec["mpv Exec Process"]
+        end
+
+        subgraph YTMusic["ytmusic (Audio Client)"]
+            MU_Cmd["Cobra CLI Bootstrapper"] --> MU_UI["Bubble Tea UI"]
+            MU_UI --> MU_DL["Downloader Engine"]
+            MU_UI --> MU_Play["Beep Audio Engine"]
+        end
+    end
+
+    %% External Processes
+    VP_DL -->|exec.Command| YTDLP["yt-dlp Binary"]
+    MU_DL -->|exec.Command| YTDLP
+    YTDLP -->|Raw Streams| FFMPEG["ffmpeg Transcoder"]
+    FFMPEG -->|Merge MP4| VP_Local["Local downloads / Cache"]
+    FFMPEG -->|Extract MP3| MU_Local["Local downloads / Cache"]
+
+    VP_Exec -->|Stream Video/Audio| MPV["mpv Engine"]
+    MU_Play -->|Volume & Resampling| Speaker["gopxl/beep Speaker"]
+    Speaker -->|Audio Output| Output["OS Sound Output"]
+```
+
+### ⚙️ Deep-Dive Engine Architecture (Under the Hood)
+
+#### 1. 🚀 Cobra CLI Bootstrapper (`cmd/`)
+* **Flag & Argument Parsing**: Built on top of `spf13/cobra`, the bootstrapper parses runtime configuration parameters (`--limit`, `--cookies`, `--cookies-from-browser`, `--vo`, `--check`) and environment overrides.
+* **Environment & Dependency Check**: Executes pre-flight scans verifying that external binaries (`yt-dlp`, `ffmpeg`, `mpv`) and CGO audio headers exist on the host system before spawning the interface.
+* **TUI Lifecyle Management**: Initializes application state structs and bootstraps the main event loop.
+
+#### 2. 🖥️ Bubble Tea Reactive TUI Engine (`internal/ui/`)
+* **Model-View-Update (MVU) Loop**: Powered by `charmbracelet/bubbletea` (Elm architecture pattern). User keystrokes are received as `tea.Msg` events, processed in pure `Update()` functions, and rendered deterministically in `View()`.
+* **Asynchronous Command Orchestration**: Non-blocking network queries and media downloads run in isolated goroutines, dispatching `tea.Cmd` response messages back into the main event loop without freezing user interface animations.
+* **Styling & Layout Rendering**: Uses `charmbracelet/lipgloss` for cyberpunk neon borders, HSL gradient text, and dynamic viewport calculation, alongside `charmbracelet/bubbles` for text input inputs and progress bar components.
+
+#### 3. 📥 Asynchronous Downloader Engine (`internal/downloader/`)
+* **Metadata Extraction**: Spawns sub-processes of `yt-dlp` using Go's `os/exec.Command` with flags (`--dump-json`, `--flat-playlist`). Reads standard output streams in real-time to parse JSON video metadata (ID, title, channel, duration, view count) into strongly-typed Go structs.
+* **Transcoding & Multiplexing Pipe**:
+  * **Video (`ytplayer`)**: Invokes `yt-dlp` to download best-quality separate video and audio streams, piping them to `ffmpeg` for container multiplexing into high-definition `.mp4` files inside `downloads/`.
+  * **Audio (`ytmusic`)**: Triggers `yt-dlp` audio extraction and uses `ffmpeg` to transcode streams into `.mp3` files formatted specifically for low-latency PCM decoding.
+* **Real-time Progress Parsing**: Intercepts `stdout` lines matching percentage regex patterns (`[download] XX.X%`), emitting real-time progress update messages to the TUI progress bar component.
+
+#### 4. 🎬 `mpv` Video Process Controller (`yt-player/internal/player/`)
+* **Terminal Handover Protocol**: Uses Bubble Tea's `tea.ExecProcess` wrapper. When a user streams a video, the TUI loop is cleanly suspended, handing standard input/output over to the native `mpv` binary.
+* **Hardware & Terminal Video Drivers**: Leverages `mpv`'s video output (`--vo`) capabilities, allowing seamless switching between external GUI windows (`gpu`, `x11`) and terminal graphics rendering (`tct`, `sixel`, `kitty`).
+* **Auto-Resume**: Upon `mpv` exit or termination signal, the terminal buffer is restored, and the Bubble Tea TUI seamlessly resumes playback state.
+
+#### 5. 🔊 Beep Audio Engine & CGO Speaker (`yt-song/internal/player/`)
+* **PCM Buffer Decoding**: Built using `gopxl/beep`. Reads local `.mp3` audio files and streams them into floating-point PCM audio buffers.
+* **Logarithmic Volume Control**: Rather than simple linear volume scaling, volume adjustments use a logarithmic scale (`math.Pow`) to match natural human auditory perception curves.
+* **Low-Level OS Sound Integration**: Uses CGO bindings to interface directly with OS native sound system APIs:
+  * **Linux**: ALSA (`libasound2`) / PulseAudio / PipeWire.
+  * **macOS**: CoreAudio.
+  * **Windows**: WASAPI.
+
+---
+
+## 🚀 System Requirements & Setup
+
+Before compiling, make sure your operating system has the necessary external libraries and executable tools installed.
+
+### 1. External Media CLI Utilities
+Both applications require **`yt-dlp`** and **`ffmpeg`**. In addition, `ytplayer` requires **`mpv`**.
+
+#### **Debian/Ubuntu**
+```bash
+sudo apt-get update
+sudo apt-get install -y mpv ffmpeg nodejs
+```
+
+#### **macOS (via Homebrew)**
+```bash
+brew install mpv ffmpeg nodejs
+```
+
+> [!TIP]
+> Node.js or Deno are optional but highly recommended to help `yt-dlp` bypass YouTube's signature bot blocks.
+
+#### **Installing/Updating `yt-dlp` (Recommended)**
+Ensure you have the latest `yt-dlp` build to handle changing YouTube API formats. The tools will check `./bin/yt-dlp` first, falling back to your system `$PATH`.
+```bash
+sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
+sudo chmod a+rx /usr/local/bin/yt-dlp
+```
+
+### 2. Audio Library Headers (Linux Only - Required for compilation)
+`ytmusic` compiles low-level Go bindings to talk directly to your system's ALSA speakers:
+
+* **Debian/Ubuntu**:
+  ```bash
+  sudo apt-get install -y libasound2-dev
+  ```
+* **Fedora/CentOS/RHEL**:
+  ```bash
+  sudo dnf install alsa-lib-devel
+  ```
+* **macOS**: No additional headers needed (native CoreAudio support).
+
+---
+
+## 🛠️ Compilation & Installation
+
+### 📦 Download via Ubuntu PPA
+
+```bash
+sudo add-apt-repository ppa:kamalchad/ytmusic
+sudo apt update
+sudo apt install ytmusic
+```
+
+> [!WARNING]
+> **Disclaimer**: Installing via PPA automatically includes all necessary packages (`yt-dlp`, `mpv`, `ffmpeg`, `libasound2-dev`) along with the binary, which may be **600 – 700 MB** in total download size.
+
+#### ⚠️ Possible Errors & Troubleshooting
+
+* **Outdated `yt-dlp` Version (`403 Forbidden` / Bot Block Errors)**:
+  System or PPA repositories may package an older version of `yt-dlp` that causes playback/search failures with YouTube API changes. Upgrade `yt-dlp` to the latest release using pip:
+  ```bash
+  python3 -m pip install -U yt-dlp
+  ```
+  or update directly via official GitHub binary:
+  ```bash
+  sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
+  sudo chmod a+rx /usr/local/bin/yt-dlp
+  ```
+
+* **Missing Audio Backend Libraries**:
+  If audio output or CGO bindings fail to launch, ensure sound packages are installed:
+  ```bash
+  sudo apt-get install -y libasound2-dev alsa-utils
+  ```
+
+---
+
+### 📦 Download via npm
+
+```bash
+npm install -g yt-cli-terminal
+ytplayer --check
+```
+
+This installs the `ytplayer`/`ytcli` (video) and `ytmusic`/`ytsong` (audio) commands. The postinstall step downloads the prebuilt binaries for your platform from the matching GitHub release and verifies their SHA-256 checksums. Supported platforms follow the release matrix (Linux amd64, macOS amd64/arm64, Windows amd64); on Debian/Ubuntu arm64 use the `.deb` asset instead.
+
+> [!NOTE]
+> npm only delivers the two Go binaries. The runtime dependencies must still be on your `PATH`: **`mpv`** (video playback), **`ffmpeg`** and **`yt-dlp`** (both tools) — see [System Requirements](#-system-requirements--setup). Run `ytplayer --check` (or `ytmusic --check`) to verify.
+
+---
+
+### 🎵 `ytmusic` (Audio Client via Script)
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ping-Phantom39/yt-cli/main/yt-song/scripts/install.sh | bash
+```
+
+---
+
+### 🎬 `ytplayer` (Video Client via Script)
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ping-Phantom39/yt-cli/main/yt-player/scripts/install.sh | bash
+```
+
+### Manual Compilation from Source
+Ensure you have **Go 1.22+** installed on your system. Navigate to the desired module directory to build:
+
+#### Build `ytplayer`
+```bash
+cd yt-player
+go build -o ../bin/ytplayer main.go
+```
+
+#### Build `ytmusic`
+```bash
+cd yt-song
+go build -o ../bin/ytmusic main.go
+```
+
+---
+
+## 🕹️ Interactive Controls & Usage
+
+### Run ytmusic from anywhere(global access)
+
+
+### 1. `ytplayer` (Video Client)
+
+Start the player and launch the interactive terminal interface:
+```bash
+./bin/ytplayer
+```
+Or search directly from startup:
+```bash
+./bin/ytplayer "cyberpunk synthwave lofi"
+```
+
+#### **Options and Flags**
+* `-l, --limit int`: Maximum search results to query (default: `15`).
+* `-q, --quality string`: Max playback/download quality (e.g. `best`, `1080`, `720`, `480`, `360`, `audio`) (default: `best`).
+* `-m, --local`: Start directly in Local Offline Video mode.
+* `--cookies string`: Custom file path containing exported session cookies.
+* `--cookies-from-browser string`: Extract session cookies directly from a specific browser (e.g. `chrome`, `firefox`, `safari`, `brave`, `edge`).
+* `--vo string`: Override the `mpv` video output driver (e.g., `tct`, `sixel`, `kitty`, `gpu`). Useful for streaming inside headless/SSH sessions.
+* `--check`: Quick check of local media tools and dependency status.
+
+#### **TUI Keyboard Shortcuts**
+* `[/]` — Focus the search bar to enter queries or filter local files.
+* `[m]` — Toggle between **Online YouTube Mode** and **Local Offline Video Mode**.
+* `[v]` or `[Tab]` — Cycle through video quality presets (**Best/4K** ➔ **1080p** ➔ **720p** ➔ **480p** ➔ **360p** ➔ **Audio Only 🎵**).
+* `[1] - [6]` — Quick jump to quality preset (`1: 4K/Best`, `2: 1080p`, `3: 720p`, `4: 480p`, `5: 360p`, `6: Audio Only`).
+* `[Enter]` — Stream the highlighted video using `mpv` with the selected quality preset.
+* `[d]` — Background download the video as high-quality `.mp4` into `downloads/`.
+* `[Esc]` — Unfocus search bar and return to result browsing.
+* `[q]` or `[Ctrl+C]` — Quit the application.
+
+---
+
+### 2. `ytmusic` (Audio Client)
+
+Start the music player:
+```bash
+./bin/ytmusic
+```
+Or start with a search query:
+```bash
+./bin/ytmusic "lofi beats for studying"
+```
+
+#### **Options and Flags**
+* `-l, --limit int`: Maximum search results to query (default: `15`).
+* `-m, --local`: Start directly in Local Offline Music mode.
+* `-v, --volume float`: Starting volume level (0.0 to 1.0) (default: `0.8`).
+* `--cookies string`: Custom Netscape format cookies file path.
+* `--cookies-from-browser string`: Load cookies from a browser profile to avoid bot bans.
+* `--check`: Verify local configuration, FFmpeg, yt-dlp, and audio device capability.
+
+#### **TUI Keyboard Shortcuts**
+* `[/]` — Focus the search bar to search online tracks or filter local library.
+* `[m]` — Toggle between **Online YouTube Mode** and **Local Offline Music Mode**.
+* `[Enter]` (on result) — Download/buffer and stream audio directly via system speaker.
+* `[d]` &mdash; Download song permanently to `./downloads/<Song_Title>.mp3`.
+* `[Space]` &mdash; Pause/Resume playback.
+* `[s]` &mdash; Stop playback.
+* `[Left]` / `[Right]` or `[h]` / `[l]` &mdash; Seek backward/forward by 5 seconds.
+* `[` / `]` &mdash; Adjust volume down/up by 5% (Logarithmic scale).
+* `[Esc]` &mdash; Unfocus search input.
+* `[q]` or `[Ctrl+C]` &mdash; Stop playback, cancel active downloads, and exit.
+
+---
+
+## 🍪 Bypassing Anti-Bot Blocking
+
+When running these tools on servers (VPS, Cloud environments) or restricted subnets, YouTube may throw HTTP `403 Forbidden` or CAPTCHA errors. Use the following integration options to supply personal session cookies:
+
+1. **Browser Extraction (Local Client Only)**:
+   Instruct the downloader to pull cookies directly from your active browser profile:
+   ```bash
+   ./bin/ytmusic --cookies-from-browser chrome "vaporwave"
+   ```
+2. **Netscape Cookies File (Server/Remote)**:
+   Export cookies using a browser extension (such as *Get cookies.txt LOCALLY*) to a text file (e.g., `cookies.txt`). Place it in the app directory or pass it as a flag:
+   ```bash
+   ./bin/ytplayer --cookies ./cookies.txt "synthwave"
+   ```
+
+---
+
+## 📁 Codebase Layout
+
+```text
+yt-song-cli/
+├── yt-player/                 # Video TUI Application (ytplayer module)
+│   ├── cmd/                   # Cobra commands & flags definitions
+│   ├── internal/              # Core business logic
+│   ├── go.mod                 # Module requirements
+│   └── README.md              # Video project documentation
+│
+└── yt-song/                   # Audio TUI Application (ytmusic module)
+    ├── cmd/                   # Cobra CLI commands & flags
+    ├── internal/              # Core business logic
+    ├── go.mod                 # Module requirements
+    └── README.md              # Audio project documentation
+```
+
+### 🔗 Quick Navigation
+
+* **Video Player (`yt-player`):**
+  * Entry point: [yt-player/main.go](yt-player/main.go)
+  * Readme: [yt-player/README.md](yt-player/README.md)
+* **Audio Player (`yt-song`):**
+  * Entry point: [yt-song/main.go](yt-song/main.go)
+  * Readme: [yt-song/README.md](yt-song/README.md)
+
+---
+
+# Run `ytmusic` Globally Using a Wrapper Script(Possible Encounter Issue)
+
+If `ytmusic` requires a local `--cookies.txt` file, creating a symbolic link with `ln -s` is **not enough**. A symbolic link only points to the executable—it **does not change the current working directory**.
+
+As a result, when you run:
+
+```bash
+ytmusic
+```
+
+from another directory, the application searches for `--cookies.txt` in your **current working directory** instead of the directory containing the binary.
+
+## Solution
+
+Create a **wrapper script** in `/usr/local/bin` that changes to the directory containing the binary before executing it.
+
+### Step 1: Create the wrapper script
+
+```bash
+sudo nano /usr/local/bin/ytmusic
+```
+
+### Step 2: Add the following contents
+
+```bash
+#!/bin/bash
+
+cd /home/codespace/ || exit 1
+exec ./ytmusic "$@"
+```
+
+> **Note:** Replace `/home/codespace/` with the directory where your `ytmusic` binary and `.env` file are located.
+
+### Step 3: Make the wrapper executable
+
+```bash
+sudo chmod +x /usr/local/bin/ytmusic
+```
+
+### Step 4: Run the application
+
+Now you can run the application from **any directory**:
+
+```bash
+ytmusic
+```
+
+## How It Works
+
+The wrapper script performs the following steps:
+
+1. Changes the current working directory to the directory containing the binary.
+2. Executes the `ytmusic` binary.
+3. Forwards any command-line arguments to the application using `"$@"`.
+
+Because the working directory is correct, the application can successfully locate the local `.env` file.
+
+## Why Not Use a Symbolic Link?
+
+For example:
+
+```bash
+sudo ln -s /home/codespace/ytmusic /usr/local/bin/ytmusic
+```
+
+Although this allows the command to be found in your `PATH`, it **does not** change the working directory.
+
+If the Go application loads `.env` like this:
+
+```go
+godotenv.Load()
+```
+
+or
+
+```go
+os.Open(".env")
+```
+
+it searches for:
+
+```
+<current-working-directory>/.env
+```
+
+instead of:
+
+```
+/home/codespace/.env
+```
+
+Therefore, a wrapper script is the simplest solution when you do not want to modify the Go source code.
+
+## Similar work for the ytplayer binary  file too
+
+## Summary
+
+- ✅ Works globally from any directory.
+- ✅ No changes to the Go application are required.
+- ✅ Ensures `.env` is always loaded from the correct location.
+- ✅ Passes all command-line arguments to the application.
+
+## 📄 License
+
+This project is licensed under the MIT License. See individual directories for any localized licenses or dependency notes.

package/npm/bin/_run.js

@@ -0,0 +1,31 @@
+'use strict';
+// Shared launcher for the npm bin shims. Spawns the postinstall-downloaded
+// binary with inherited stdio so the Bubble Tea TUI works normally.
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function run(binary) {
+  const exe = process.platform === 'win32' ? `${binary}.exe` : binary;
+  const bin = path.join(__dirname, '..', 'vendor', exe);
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `[yt-cli-terminal] ${exe} not found.\n` +
+        'The postinstall download probably failed (no network, or no prebuilt\n' +
+        'binary for this platform). Reinstall with network access:\n' +
+        '  npm install -g yt-cli-terminal\n' +
+        'You still need the runtime dependencies on PATH: mpv (ytplayer),\n' +
+        'ffmpeg and yt-dlp (both tools). Run `ytplayer --check` to verify.\n' +
+        'See https://github.com/Ping-Phantom39/yt-cli#readme for alternatives.'
+    );
+    process.exit(1);
+  }
+  const result = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`[yt-cli-terminal] failed to launch ${exe}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+module.exports = { run };

package/npm/bin/ytcli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('./_run').run('ytplayer');

package/npm/bin/ytmusic.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('./_run').run('ytmusic');

package/npm/bin/ytplayer.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('./_run').run('ytplayer');

package/npm/bin/ytsong.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('./_run').run('ytmusic');

package/npm/install.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * postinstall downloader for the `yt-cli-terminal` npm package.
+ *
+ * Fetches the prebuilt `ytplayer` / `ytmusic` binaries for the current
+ * platform from the GitHub release matching this package's version and
+ * places them in ./vendor. No runtime dependencies, Node >= 16 only.
+ *
+ * Environment overrides:
+ *   YT_CLI_SKIP_POSTINSTALL=1  skip downloading (leave vendor/ empty)
+ *   YT_CLI_VERSION=x.y.z        release tag to download (default: package.json version)
+ *   YT_CLI_REPO=owner/repo      GitHub repo (default: Ping-Phantom39/yt-cli)
+ *   YT_CLI_BASE_URL=<url>       override release base URL (trailing /v<tag>/<asset> appended)
+ *   YT_CLI_VENDOR_DIR=<dir>     override download directory (default: ./vendor)
+ *   YT_CLI_PLATFORM / YT_CLI_ARCH  override platform detection (testing)
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+
+const REPO = process.env.YT_CLI_REPO || 'Ping-Phantom39/yt-cli';
+const PKG_VERSION = (process.env.YT_CLI_VERSION || require('../package.json').version).replace(/^v/, '');
+const TAG = `v${PKG_VERSION}`;
+const BASE_URL = (process.env.YT_CLI_BASE_URL || `https://github.com/${REPO}/releases/download`).replace(/\/+$/, '');
+const VENDOR_DIR = process.env.YT_CLI_VENDOR_DIR || path.join(__dirname, 'vendor');
+
+const BINARIES = ['ytplayer', 'ytmusic'];
+
+// Release matrix in .github/workflows/release.yml ships raw binaries for:
+const SUPPORTED = new Set(['linux/amd64', 'darwin/amd64', 'darwin/arm64', 'windows/amd64']);
+
+function currentPlatform() {
+  return {
+    platform: process.env.YT_CLI_PLATFORM || process.platform,
+    arch: process.env.YT_CLI_ARCH || process.arch,
+  };
+}
+
+function targetTriple() {
+  const { platform, arch } = currentPlatform();
+  let osPart;
+  if (platform === 'linux') osPart = 'linux';
+  else if (platform === 'darwin') osPart = 'darwin';
+  else if (platform === 'win32') osPart = 'windows';
+  else {
+    throw new Error(
+      `Unsupported platform "${platform}" (arch "${arch}"). ` +
+      `Prebuilt binaries exist for: ${[...SUPPORTED].join(', ')}. ` +
+      'See https://github.com/Ping-Phantom39/yt-cli#readme for other install methods.'
+    );
+  }
+  let archPart;
+  if (arch === 'x64') archPart = 'amd64';
+  else if (arch === 'arm64') archPart = 'arm64';
+  else {
+    throw new Error(
+      `Unsupported architecture "${arch}" on "${platform}". ` +
+      `Prebuilt binaries exist for: ${[...SUPPORTED].join(', ')}.`
+    );
+  }
+  const triple = `${osPart}/${archPart}`;
+  if (!SUPPORTED.has(triple)) {
+    throw new Error(
+      `No prebuilt binaries for ${triple}. ` +
+      'On Debian/Ubuntu arm64 use the .deb release asset, otherwise build from source: ' +
+      'https://github.com/Ping-Phantom39/yt-cli#readme'
+    );
+  }
+  return { osPart, archPart, isWindows: osPart === 'windows' };
+}
+
+// Release asset filename, e.g. ytplayer-linux-amd64 / ytmusic-windows-amd64.exe
+function assetName(binary) {
+  const { osPart, archPart, isWindows } = targetTriple();
+  return `${binary}-${osPart}-${archPart}${isWindows ? '.exe' : ''}`;
+}
+
+// On-disk filename inside vendor/, e.g. ytplayer / ytmusic.exe
+function vendorName(binary) {
+  return binary + (targetTriple().isWindows ? '.exe' : '');
+}
+
+function get(url, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith('https:') ? https : http;
+    const req = lib.get(
+      url,
+      { headers: { 'User-Agent': 'yt-cli-terminal-installer' } },
+      (res) => {
+        if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && redirects > 0) {
+          res.resume();
+          resolve(get(new URL(res.headers.location, url).toString(), redirects - 1));
+          return;
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+          return;
+        }
+        resolve(res);
+      }
+    );
+    req.on('error', reject);
+  });
+}
+
+async function downloadFile(url, dest) {
+  const res = await get(url);
+  await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.part`;
+  try {
+    await new Promise((resolve, reject) => {
+      const out = fs.createWriteStream(tmp, { mode: 0o755 });
+      out.on('finish', resolve);
+      out.on('error', reject);
+      res.on('error', reject);
+      res.pipe(out);
+    });
+    await fs.promises.rename(tmp, dest);
+    if (process.platform !== 'win32') {
+      await fs.promises.chmod(dest, 0o755);
+    }
+  } finally {
+    await fs.promises.rm(tmp, { force: true });
+  }
+}
+
+async function fetchText(url) {
+  const res = await get(url);
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(file);
+    stream.on('error', reject);
+    stream.on('data', (d) => hash.update(d));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+// Strictly verify against the release SHA256SUMS.txt when available;
+// older tags predate it, so only warn if the sums file itself is missing.
+async function verifyChecksums(pairs) {
+  let sums;
+  try {
+    sums = await fetchText(`${BASE_URL}/${TAG}/SHA256SUMS.txt`);
+  } catch (err) {
+    console.warn(`[yt-cli-terminal] warning: no SHA256SUMS.txt for ${TAG} (${err.message}); skipping checksum verification`);
+    return;
+  }
+  const expected = new Map();
+  for (const line of sums.split('\n')) {
+    const m = line.match(/^([0-9a-f]{64})\s+\*?(\S+)\s*$/i);
+    if (m) expected.set(m[2], m[1].toLowerCase());
+  }
+  for (const { asset, file } of pairs) {
+    const sum = expected.get(asset);
+    if (!sum) {
+      console.warn(`[yt-cli-terminal] warning: no checksum entry for ${asset}; skipping`);
+      continue;
+    }
+    const actual = await sha256File(file);
+    if (actual !== sum) {
+      throw new Error(
+        `Checksum mismatch for ${asset} (expected ${sum}, got ${actual}). ` +
+        'Delete node_modules and reinstall, or report an issue at ' +
+        'https://github.com/Ping-Phantom39/yt-cli/issues'
+      );
+    }
+    console.log(`[yt-cli-terminal] checksum OK: ${asset}`);
+  }
+}
+
+async function main() {
+  if (process.env.YT_CLI_SKIP_POSTINSTALL) {
+    console.log('[yt-cli-terminal] YT_CLI_SKIP_POSTINSTALL set; skipping binary download');
+    return;
+  }
+  await fs.promises.mkdir(VENDOR_DIR, { recursive: true });
+  const pairs = [];
+  for (const binary of BINARIES) {
+    const asset = assetName(binary); // throws on unsupported platform
+    const url = `${BASE_URL}/${TAG}/${asset}`;
+    const file = path.join(VENDOR_DIR, vendorName(binary));
+    console.log(`[yt-cli-terminal] downloading ${asset} ...`);
+    await downloadFile(url, file);
+    pairs.push({ asset, file });
+  }
+  await verifyChecksums(pairs);
+  console.log(`[yt-cli-terminal] installed ytplayer + ytmusic ${TAG} to ${VENDOR_DIR}`);
+  console.log('[yt-cli-terminal] note: ytplayer needs mpv, and both tools need ffmpeg + yt-dlp on PATH (try `ytplayer --check`)');
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`[yt-cli-terminal] install failed: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { assetName, vendorName, targetTriple, TAG, BASE_URL, VENDOR_DIR, BINARIES };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "yt-cli-terminal",
+  "version": "1.4.0",
+  "description": "Cyberpunk terminal YouTube video player (ytplayer) and music player (ytmusic). Installs prebuilt binaries from GitHub releases.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ping-Phantom39/yt-cli.git"
+  },
+  "homepage": "https://github.com/Ping-Phantom39/yt-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Ping-Phantom39/yt-cli/issues"
+  },
+  "keywords": [
+    "youtube",
+    "terminal",
+    "tui",
+    "mpv",
+    "music",
+    "video",
+    "cli",
+    "yt-dlp"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "bin": {
+    "ytplayer": "./npm/bin/ytplayer.js",
+    "ytcli": "./npm/bin/ytcli.js",
+    "ytmusic": "./npm/bin/ytmusic.js",
+    "ytsong": "./npm/bin/ytsong.js"
+  },
+  "scripts": {
+    "postinstall": "node ./npm/install.js",
+    "test": "node --test npm/"
+  },
+  "files": [
+    "npm/bin/",
+    "npm/install.js",
+    "README.md",
+    "LICENSE"
+  ]
+}