@0xsharon/synco 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 0xSHARON
+
+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

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @0xsharon/synco
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Get time-synchronized LRC format lyrics for your music in Node.js and CLI.
+
+[![npm version](https://img.shields.io/npm/v/@0xsharon/synco.svg)](https://www.npmjs.com/package/@0xsharon/synco)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A fast, lightweight, and modern Node.js library and command-line tool that searches and downloads synchronized lyrics (`.lrc` files) from multiple online lyrics providers.
+
+---
+
+## ✨ Features
+
+- **⏱️ Synchronized (.lrc) Support:** Retrieves time-stamped lyrics ready for any music player or karaoke system.
+- **📄 Plaintext & Synced Modes:** Easily choose between synchronized (`--synced-only`) or plaintext (`--plain-only`) lyrics.
+- **🎤 Enhanced Word-by-Word Lyrics:** Supports word-level karaoke timing tags (`<mm:ss.xx>`) when available.
+- **🌐 Translations:** Retrieve translated lyrics alongside original lines.
+- **🔍 Intelligent Fallback & Fuzzy Matching:** Uses token set ratio similarity algorithms to accurately match tracks and filter out extraneous results.
+- **⚡ Dual ESM & CommonJS:** Native support for both `import` and `require()`, complete with TypeScript declarations.
+- **💻 CLI & Programmatic API:** Use directly from your terminal or integrate seamlessly into your Node.js apps.
+
+---
+
+## 📦 Installation
+
+### Global CLI
+```bash
+npm install -g @0xsharon/synco
+```
+Or run directly with `npx`:
+```bash
+npx @0xsharon/synco "SEARCH_TERM"
+```
+
+### Local Project Dependency
+```bash
+npm install @0xsharon/synco
+```
+```bash
+pnpm add @0xsharon/synco
+```
+```bash
+yarn add @0xsharon/synco
+```
+
+---
+
+## 🚀 CLI Usage
+
+```bash
+synco "SEARCH_TERM" [options]
+```
+*(Also available as `syncedlyrics` alias)*
+
+### Examples:
+```bash
+# Basic search (downloads to "{search_term}.lrc" by default)
+synco "Bohemian Rhapsody Queen"
+
+# Save to a custom file
+synco "Blinding Lights The Weeknd" -o "blinding_lights.lrc"
+
+# Search specific providers only
+synco "bad guy billie eilish" -p lrclib megalobiz
+
+# Get plaintext lyrics only
+synco "Shape of You Ed Sheeran" --plain-only
+
+# Enhanced word-by-word karaoke format
+synco "Shape of You Ed Sheeran" --enhanced
+
+# Enable verbose debug logs
+synco "Hotel California Eagles" -v
+```
+
+### Options
+
+| Flag | Short | Description | Default |
+| --- | --- | --- | --- |
+| `--output <path>` | `-o` | Output file path (`{search_term}` is replaced dynamically) | `"{search_term}.lrc"` |
+| `--providers <list>` | `-p` | Space-separated list of providers to search | *all available* |
+| `--lang <code>` | `-l` | Translation language code (e.g., `es`, `de`, `fr`) | `undefined` |
+| `--plain-only` | | Only look for plain text (not synced) lyrics | `false` |
+| `--synced-only` | | Only look for synced lyrics | `false` |
+| `--enhanced` | | Word-by-word karaoke synchronized lyrics | `false` |
+| `--token <token>` | | Optional custom Musixmatch user token | `undefined` |
+| `--verbose` | `-v` | Output debug logs to stderr | `false` |
+| `--version` | `-V` | Output version number | |
+| `--help` | `-h` | Display help screen | |
+
+---
+
+## 🛠️ Programmatic Usage (Node.js & TypeScript)
+
+### TypeScript / ES Modules (`import`)
+```typescript
+import synco, { search } from '@0xsharon/synco';
+
+// Simple search
+const lrc = await search('Bohemian Rhapsody Queen');
+console.log(lrc);
+
+// Or call the default export directly
+const lrcText = await synco('Hotel California Eagles');
+```
+
+### CommonJS (`require`)
+```javascript
+const synco = require('@0xsharon/synco');
+
+async function main() {
+  const lrc = await synco.search('Blinding Lights The Weeknd');
+  console.log(lrc);
+}
+main();
+```
+
+### Advanced Options
+
+```typescript
+import { search } from '@0xsharon/synco';
+
+const lrc = await search('bad guy billie eilish', {
+  // Only search specific providers
+  providers: ['lrclib', 'megalobiz'],
+
+  // Only return synchronized lyrics (or plain-only)
+  syncedOnly: true,
+
+  // Automatically save to disk ({search_term} placeholder supported)
+  savePath: './lyrics/{search_term}.lrc',
+
+  // Word-level karaoke timing
+  enhanced: false,
+
+  // Request timeout in milliseconds
+  timeoutMs: 8000,
+
+  // Enable debug logging
+  verbose: true,
+});
+```
+
+### Helper Utilities Exported
+```typescript
+import {
+  syncedToPlaintext,
+  identifyLyricsType,
+  formatTime,
+  strScore,
+  Lyrics,
+  TargetType,
+} from 'synco';
+
+// Convert synced LRC to clean plaintext
+const plain = syncedToPlaintext(lrc);
+
+// Check if string contains synchronized timestamps
+const type = identifyLyricsType(lrc); // 'synced' | 'plaintext' | 'invalid'
+
+// Format seconds into [mm:ss.xx]
+console.log(formatTime(75.5)); // "01:15.50"
+```
+
+---
+
+## 📡 Providers
+
+| Provider | Status | Synced | Word-by-Word | Translations |
+| --- | :---: | :---: | :---: | :---: |
+| **LRCLIB** (`lrclib`) | ✅ Operational | Yes | No | No |
+| **Megalobiz** (`megalobiz`) | ✅ Operational | Yes | No | No |
+| **Musixmatch** (`musixmatch`) | ✅ Operational | Yes | Yes | Yes |
+| **NetEase** (`netease`) | ✅ Operational | Yes | No | No |
+| **Genius** (`genius`) | ✅ Operational | Plaintext | No | No |
+| **Deezer** (`deezer`) | ⚠️ Fallback | Yes | No | No |
+| **Lyricsify** (`lyricsify`) | ⚠️ Fallback | Yes | No | No |
+
+---
+
+## 📄 License
+
+MIT License © 2026 [0xSHARON](https://github.com/0xSHARON)