@involvex/youtube-music-cli 0.0.0

package/README.md

@@ -0,0 +1,352 @@
+<div align="center">
+
+# 🎵 youtube-music-cli
+
+A powerful Terminal User Interface (TUI) music player for YouTube Music
+
+[![npm version](https://img.shields.io/npm/v/@involvex/youtube-music-cli.svg)](https://www.npmjs.com/package/@involvex/youtube-music-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Plugins](#plugins) • [Documentation](https://involvex.github.io/youtube-music-cli)
+
+</div>
+
+---
+
+## Features
+
+- 🎨 **Beautiful TUI** - Rich terminal interface built with React and Ink
+- 🔍 **Search** - Find songs, albums, artists, and playlists
+- 📋 **Queue Management** - Build and manage your playback queue
+- 🔀 **Shuffle & Repeat** - Multiple playback modes
+- 🎚️ **Volume Control** - Fine-grained volume adjustment
+- 💡 **Smart Suggestions** - Discover related tracks
+- 🎨 **Themes** - Dark, Light, Midnight, Matrix themes
+- 🔌 **Plugin System** - Extend functionality with plugins
+- ⌨️ **Keyboard-Driven** - Efficient vim-style navigation
+- 🖥️ **Headless Mode** - Run without TUI for scripting
+
+## Prerequisites
+
+**Required:**
+
+- [mpv](https://mpv.io/) - Media player for audio playback
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube audio extraction
+
+### Installing Prerequisites
+
+<details>
+<summary><b>Windows</b></summary>
+
+```bash
+# With Scoop
+scoop install mpv yt-dlp
+
+# With Chocolatey
+choco install mpv yt-dlp
+
+# With winget
+winget install mpv yt-dlp
+```
+
+</details>
+
+<details>
+<summary><b>macOS</b></summary>
+
+```bash
+brew install mpv yt-dlp
+```
+
+</details>
+
+<details>
+<summary><b>Linux</b></summary>
+
+```bash
+# Ubuntu/Debian
+sudo apt install mpv
+pip install yt-dlp
+
+# Arch Linux
+sudo pacman -S mpv yt-dlp
+
+# Fedora
+sudo dnf install mpv yt-dlp
+```
+
+</details>
+
+## Installation
+
+### npm (Recommended)
+
+```bash
+npm install -g @involvex/youtube-music-cli
+```
+
+### Bun
+
+```bash
+bun install -g @involvex/youtube-music-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/involvex/youtube-music-cli.git
+cd youtube-music-cli
+bun install
+bun run build
+bun link
+```
+
+## Usage
+
+### Interactive Mode
+
+Launch the TUI:
+
+```bash
+youtube-music-cli
+```
+
+### CLI Commands
+
+```bash
+# Play a specific track
+youtube-music-cli play <video-id>
+
+# Search for music
+youtube-music-cli search "artist or song name"
+
+# Play a playlist
+youtube-music-cli playlist <playlist-id>
+
+# Get suggestions based on current track
+youtube-music-cli suggestions
+
+# Playback control
+youtube-music-cli pause
+youtube-music-cli resume
+youtube-music-cli skip
+youtube-music-cli back
+```
+
+### Options
+
+| Flag         | Short | Description                                  |
+| ------------ | ----- | -------------------------------------------- |
+| `--theme`    | `-t`  | Theme: `dark`, `light`, `midnight`, `matrix` |
+| `--volume`   | `-v`  | Initial volume (0-100)                       |
+| `--shuffle`  | `-s`  | Enable shuffle mode                          |
+| `--repeat`   | `-r`  | Repeat mode: `off`, `all`, `one`             |
+| `--headless` |       | Run without TUI                              |
+| `--help`     | `-h`  | Show help                                    |
+
+### Examples
+
+```bash
+# Launch with matrix theme at 80% volume
+youtube-music-cli --theme=matrix --volume=80
+
+# Search and play in headless mode
+youtube-music-cli search "lofi beats" --headless
+
+# Play with shuffle enabled
+youtube-music-cli play dQw4w9WgXcQ --shuffle
+```
+
+## Keyboard Shortcuts
+
+### Global
+
+| Key         | Action          |
+| ----------- | --------------- |
+| `?`         | Show help       |
+| `/`         | Search          |
+| `p`         | Plugins manager |
+| `g`         | Suggestions     |
+| `,`         | Settings        |
+| `q` / `Esc` | Quit / Go back  |
+| `Ctrl+L`    | Refresh screen  |
+
+### Playback
+
+| Key       | Action            |
+| --------- | ----------------- |
+| `Space`   | Play / Pause      |
+| `n` / `→` | Next track        |
+| `b` / `←` | Previous track    |
+| `Shift+→` | Seek forward 10s  |
+| `Shift+←` | Seek backward 10s |
+| `=`       | Volume up         |
+| `-`       | Volume down       |
+| `s`       | Toggle shuffle    |
+| `r`       | Cycle repeat mode |
+
+### Navigation
+
+| Key       | Action    |
+| --------- | --------- |
+| `↑` / `k` | Move up   |
+| `↓` / `j` | Move down |
+| `Enter`   | Select    |
+| `Esc`     | Back      |
+
+## Plugins
+
+Extend youtube-music-cli with plugins!
+
+### Managing Plugins
+
+**TUI Mode:** Press `p` to open the plugins manager.
+
+**CLI Mode:**
+
+```bash
+# List installed plugins
+youtube-music-cli plugins list
+
+# Install from default repository
+youtube-music-cli plugins install adblock
+
+# Install from GitHub URL
+youtube-music-cli plugins install https://github.com/user/my-plugin
+
+# Enable/disable
+youtube-music-cli plugins enable my-plugin
+youtube-music-cli plugins disable my-plugin
+
+# Update
+youtube-music-cli plugins update my-plugin
+
+# Remove
+youtube-music-cli plugins remove my-plugin
+```
+
+### Available Plugins
+
+| Plugin          | Description                             |
+| --------------- | --------------------------------------- |
+| `adblock`       | Block ads and sponsored content         |
+| `lyrics`        | Display synchronized lyrics             |
+| `scrobbler`     | Scrobble to Last.fm                     |
+| `discord-rpc`   | Discord Rich Presence integration       |
+| `notifications` | Desktop notifications for track changes |
+
+### Developing Plugins
+
+See [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md) and [Plugin API Reference](docs/PLUGIN_API.md).
+
+```bash
+# Start from a template
+cp -r templates/plugin-basic my-plugin
+cd my-plugin
+
+# Edit plugin.json and index.ts
+# Install for testing
+youtube-music-cli plugins install /path/to/my-plugin
+```
+
+## Configuration
+
+Config is stored in `~/.youtube-music-cli/config.json`:
+
+```json
+{
+	"theme": "dark",
+	"volume": 70,
+	"shuffle": false,
+	"repeat": "off",
+	"streamQuality": "high"
+}
+```
+
+### Stream Quality
+
+| Quality  | Description             |
+| -------- | ----------------------- |
+| `low`    | 64kbps - Save bandwidth |
+| `medium` | 128kbps - Balanced      |
+| `high`   | 256kbps+ - Best quality |
+
+## Troubleshooting
+
+### mpv not found
+
+Ensure mpv is installed and in your PATH:
+
+```bash
+mpv --version
+```
+
+### No audio
+
+1. Check volume isn't muted (`=` to increase)
+2. Verify yt-dlp is working: `yt-dlp --version`
+3. Try a different track
+
+### TUI rendering issues
+
+Press `Ctrl+L` to refresh the screen, or try a different terminal emulator.
+
+### Plugin not loading
+
+1. Check `plugin.json` syntax is valid
+2. Verify the plugin is enabled: `youtube-music-cli plugins list`
+3. Check logs for errors
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Run tests: `bun run test`
+5. Commit: `git commit -m 'feat: add my feature'`
+6. Push: `git push origin feature/my-feature`
+7. Open a Pull Request
+
+### Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development mode
+bun run dev
+
+# Build
+bun run build
+
+# Lint and format
+bun run lint:fix
+bun run format
+
+# Type check
+bun run typecheck
+```
+
+## Tech Stack
+
+- **Runtime:** [Bun](https://bun.sh/) / Node.js
+- **UI Framework:** [Ink](https://github.com/vadimdemedes/ink) (React for CLI)
+- **Language:** TypeScript
+- **Audio:** mpv + yt-dlp
+- **API:** YouTube Music Innertube API
+
+## License
+
+MIT © [Involvex](https://github.com/involvex)
+
+---
+
+<div align="center">
+
+**[Documentation](https://involvex.github.io/youtube-music-cli)** • **[Report Bug](https://github.com/involvex/youtube-music-cli/issues)** • **[Request Feature](https://github.com/involvex/youtube-music-cli/issues)**
+
+Made with ❤️ for music lovers
+
+</div>

package/dist/eslint.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint/config").Config[];
+export default _default;

package/dist/eslint.config.js

@@ -0,0 +1,55 @@
+import pluginReact from 'eslint-plugin-react';
+import hooksPlugin from 'eslint-plugin-react-hooks';
+import { defineConfig } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+import js from '@eslint/js';
+export default defineConfig([
+    {
+        ignores: ['templates/**/*', 'plugins/**/*'],
+    },
+    {
+        files: ['**/*.{js,mjs,cjs}'],
+        plugins: { js },
+        extends: ['js/recommended'],
+        languageOptions: { globals: { ...globals.node } },
+    },
+    ...tseslint.configs.recommended,
+    {
+        files: ['**/*.{ts,mts,cts,jsx,tsx}'],
+        languageOptions: {
+            globals: { ...globals.node },
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            parserOptions: {
+                projectService: true,
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+    },
+    {
+        files: ['**/*.jsx', '**/*.tsx'],
+        ...pluginReact.configs.flat['recommended'],
+        plugins: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'react-hooks': hooksPlugin,
+        },
+        settings: {
+            react: { version: 'detect' },
+            jsxRuntime: 'automatic',
+        },
+        rules: {
+            ...hooksPlugin.configs.recommended.rules,
+            'react/react-in-jsx-scope': 'off',
+            'react/jsx-uses-react': 'off',
+            '@typescript-eslint/no-unused-vars': [
+                'error',
+                {
+                    argsIgnorePattern: '^_',
+                    varsIgnorePattern: '^_',
+                    caughtErrorsIgnorePattern: '^_',
+                },
+            ],
+        },
+    },
+]);

package/dist/source/app.d.ts

@@ -0,0 +1,4 @@
+import type { Flags } from './types/cli.types.ts';
+export default function App({ flags }: {
+    flags?: Flags;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/source/app.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Root application component
+import { useApp } from 'ink';
+import Main from "./main.js";
+import { useEffect } from 'react';
+// Handle unmounting
+let unmount = null;
+export default function App({ flags }) {
+    const { exit } = useApp();
+    // Store unmount function globally
+    useEffect(() => {
+        if (!unmount) {
+            unmount = exit;
+        }
+    }, [exit]);
+    return _jsx(Main, { flags: flags });
+}

package/dist/source/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/source/cli.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import App from "./app.js";
+import { render } from 'ink';
+import meow from 'meow';
+import { getPluginInstallerService } from "./services/plugin/plugin-installer.service.js";
+import { getPluginUpdaterService } from "./services/plugin/plugin-updater.service.js";
+import { getPluginRegistryService } from "./services/plugin/plugin-registry.service.js";
+const cli = meow(`
+	Usage
+	  $ youtube-music-cli
+	  $ youtube-music-cli play <track-id>
+	  $ youtube-music-cli search <query>
+	  $ youtube-music-cli playlist <playlist-id>
+	  $ youtube-music-cli suggestions
+	  $ youtube-music-cli pause
+	  $ youtube-music-cli resume
+	  $ youtube-music-cli skip
+	  $ youtube-music-cli back
+
+	Plugin Commands
+	  $ youtube-music-cli plugins list
+	  $ youtube-music-cli plugins install <name|url>
+	  $ youtube-music-cli plugins remove <name>
+	  $ youtube-music-cli plugins update <name>
+	  $ youtube-music-cli plugins enable <name>
+	  $ youtube-music-cli plugins disable <name>
+
+	Options
+	  --theme, -t    Theme to use (dark, light, midnight, matrix)
+	  --volume, -v   Initial volume (0-100)
+	  --shuffle, -s   Enable shuffle mode
+	  --repeat, -r   Repeat mode (off, all, one)
+	  --headless     Run without TUI (just play)
+	  --help, -h     Show this help
+
+	Examples
+	  $ youtube-music-cli
+	  $ youtube-music-cli play dQw4w9WgXcQ
+	  $ youtube-music-cli search "Rick Astley"
+	  $ youtube-music-cli play dQw4w9WgXcQ --headless
+	  $ youtube-music-cli plugins install adblock
+`, {
+    importMeta: import.meta,
+    flags: {
+        theme: {
+            type: 'string',
+            shortFlag: 't',
+        },
+        volume: {
+            type: 'number',
+            shortFlag: 'v',
+        },
+        shuffle: {
+            type: 'boolean',
+            shortFlag: 's',
+            default: false,
+        },
+        repeat: {
+            type: 'string',
+            shortFlag: 'r',
+        },
+        headless: {
+            type: 'boolean',
+            default: false,
+        },
+        help: {
+            type: 'boolean',
+            shortFlag: 'h',
+            default: false,
+        },
+    },
+    autoVersion: true,
+    autoHelp: false,
+});
+if (cli.flags.help) {
+    cli.showHelp(0);
+}
+// Handle plugin commands
+const command = cli.input[0];
+const args = cli.input.slice(1);
+if (command === 'plugins') {
+    const subCommand = args[0];
+    const pluginArg = args[1];
+    void (async () => {
+        const installer = getPluginInstallerService();
+        const updater = getPluginUpdaterService();
+        const registry = getPluginRegistryService();
+        // Load existing plugins
+        await registry.loadAllPlugins();
+        switch (subCommand) {
+            case 'list': {
+                const plugins = registry.getAllPlugins();
+                if (plugins.length === 0) {
+                    console.log('No plugins installed.');
+                }
+                else {
+                    console.log('Installed plugins:');
+                    for (const plugin of plugins) {
+                        const status = plugin.enabled ? '●' : '○';
+                        console.log(`  ${status} ${plugin.manifest.name} v${plugin.manifest.version}`);
+                    }
+                }
+                process.exit(0);
+                break;
+            }
+            case 'install': {
+                if (!pluginArg) {
+                    console.error('Usage: youtube-music-cli plugins install <name|url>');
+                    process.exit(1);
+                }
+                console.log(`Installing ${pluginArg}...`);
+                let result;
+                if (pluginArg.startsWith('http')) {
+                    result = await installer.installFromGitHub(pluginArg);
+                }
+                else {
+                    result = await installer.installFromDefaultRepo(pluginArg);
+                }
+                if (result.success) {
+                    console.log(`✓ Successfully installed ${result.pluginId}`);
+                }
+                else {
+                    console.error(`✗ Failed: ${result.error}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+                break;
+            }
+            case 'remove':
+            case 'uninstall': {
+                if (!pluginArg) {
+                    console.error('Usage: youtube-music-cli plugins remove <name>');
+                    process.exit(1);
+                }
+                console.log(`Removing ${pluginArg}...`);
+                try {
+                    await registry.unloadPlugin(pluginArg);
+                }
+                catch {
+                    // Plugin may not be loaded
+                }
+                const result = await installer.uninstall(pluginArg);
+                if (result.success) {
+                    console.log(`✓ Successfully removed ${pluginArg}`);
+                }
+                else {
+                    console.error(`✗ Failed: ${result.error}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+                break;
+            }
+            case 'update': {
+                if (!pluginArg) {
+                    console.error('Usage: youtube-music-cli plugins update <name>');
+                    process.exit(1);
+                }
+                console.log(`Updating ${pluginArg}...`);
+                const result = await updater.updatePlugin(pluginArg);
+                if (result.success) {
+                    console.log(`✓ Updated ${pluginArg} from ${result.oldVersion} to ${result.newVersion}`);
+                }
+                else {
+                    console.error(`✗ Failed: ${result.error}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+                break;
+            }
+            case 'enable': {
+                if (!pluginArg) {
+                    console.error('Usage: youtube-music-cli plugins enable <name>');
+                    process.exit(1);
+                }
+                try {
+                    await registry.enablePlugin(pluginArg);
+                    console.log(`✓ Enabled ${pluginArg}`);
+                }
+                catch (error) {
+                    console.error(`✗ Failed: ${error instanceof Error ? error.message : String(error)}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+                break;
+            }
+            case 'disable': {
+                if (!pluginArg) {
+                    console.error('Usage: youtube-music-cli plugins disable <name>');
+                    process.exit(1);
+                }
+                try {
+                    await registry.disablePlugin(pluginArg);
+                    console.log(`✓ Disabled ${pluginArg}`);
+                }
+                catch (error) {
+                    console.error(`✗ Failed: ${error instanceof Error ? error.message : String(error)}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+                break;
+            }
+            default:
+                console.error('Usage: youtube-music-cli plugins <list|install|remove|update|enable|disable>');
+                process.exit(1);
+        }
+    })();
+}
+else {
+    // Handle other direct commands
+    if (command === 'play' && args[0]) {
+        // Play specific track
+        cli.flags.playTrack = args[0];
+    }
+    else if (command === 'search' && args[0]) {
+        // Search for query
+        cli.flags.searchQuery = args.join(' ');
+    }
+    else if (command === 'playlist' && args[0]) {
+        // Play specific playlist
+        cli.flags.playPlaylist = args[0];
+    }
+    else if (command === 'suggestions') {
+        // Show suggestions
+        cli.flags.showSuggestions = true;
+    }
+    else if (command === 'pause') {
+        cli.flags.action = 'pause';
+    }
+    else if (command === 'resume') {
+        cli.flags.action = 'resume';
+    }
+    else if (command === 'skip') {
+        cli.flags.action = 'next';
+    }
+    else if (command === 'back') {
+        cli.flags.action = 'previous';
+    }
+    // Render the app
+    render(_jsx(App, { flags: cli.flags }));
+}

package/dist/source/components/common/ErrorBoundary.d.ts

@@ -0,0 +1,15 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+interface Props {
+    children: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+export declare class ErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};