@archhaze24/korg 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirill Belolipetsky
+
+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,100 @@
-# Temporary Holding Version
+# korg
 
-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.
+Kirby's music organizer. Turns a FLAC library tagged with MusicBrainz Picard into a small Opus library.
+
+One `korg run` does four steps:
+
+1. **covers**: resize and clean `cover.jpg`
+2. **lyrics**: download synced lyrics from [LRCLIB](https://lrclib.net) as `.lrc` files
+3. **encode**: FLAC to Opus (160 kbit/s VBR), MP3 is copied, covers, `.lrc` and booklets are copied along
+4. **gain**: ReplayGain for both libraries
+
+Works on Linux, macOS and Windows.
+
+## Install
+
+```sh
+brew install archhaze24/tap/korg                                          # macOS, Linux
+scoop bucket add archhaze24 https://github.com/archhaze24/scoop-bucket && scoop install korg   # Windows
+npx @archhaze24/korg --help                                               # any, via npm
+cargo install korg-cli                                                    # from source, Rust 1.89+
+```
+
+Prebuilt archives are on the [releases page](https://github.com/archhaze24/korg/releases).
+
+korg calls two external tools, so install them too (Homebrew installs them with the formula):
+
+- [`opusenc`](https://opus-codec.org/downloads/) (opus-tools)
+- [`rsgain`](https://github.com/complexlogic/rsgain) with a preset named `opus`
+
+The gain step runs `rsgain easy -p opus`, so create `opus.ini` in rsgain's presets folder:
+`~/.config/rsgain/presets/` (Linux), `~/Library/rsgain/presets/` (macOS), `%USERPROFILE%\.rsgain\presets\` (Windows).
+This is enough to get R128 tags in Opus files:
+
+```ini
+[Opus]
+OpusMode=r
+```
+
+rsgain ignores `[Opus]` in a folder that mixes Opus and MP3 and writes plain ReplayGain tags there. Use
+`[Global]` instead of `[Opus]` if you want R128 everywhere.
+
+`korg doctor` checks the tools and the preset.
+
+## Usage
+
+```sh
+korg run                                         # ./toencode -> ./encoded
+korg run -s ~/Music/toencode -d ~/Music/encoded
+korg run --skip lyrics,gain                      # leave steps out
+korg run --dry-run                               # show what would happen
+korg covers | lyrics | encode | gain             # one step only
+korg restore-names                               # undo renames after a crash
+```
+
+Source and destination can also come from `KORG_SOURCE` and `KORG_DEST`. `-j` sets parallel encodes per album
+(default: CPU cores minus 2), `-v` prints every checked file.
+
+Don't run two instances on the same folders, and don't edit the source in Picard meanwhile.
+
+## What the steps do
+
+**covers.** `cover.jpg`, `cover.jpeg`, `front.jpg` and `folder.jpg` (any case) become `cover.jpg`. A side over 2000 px
+or an EXIF rotation means resize and re-encode (quality 90, progressive); a heavy file is re-encoded only if that
+saves 10% or more. Everything else just loses its metadata. Several candidates in one folder: reported, skipped.
+
+**lyrics.** For each FLAC/MP3, LRCLIB is asked by title, artist, album and duration, then by title and artist only.
+A match needs the same title and artist (ignoring case and punctuation) and a duration within 2 s; the closest
+duration wins, the album only breaks ties. Only lyrics with timestamps are saved. An existing `.lrc` with
+timestamps is kept, one without is deleted and searched again. To search again, delete the `.lrc`.
+
+**encode.** Albums run one after another, tracks inside an album in parallel. Tags and artwork are kept; ReplayGain
+and encoder tags are dropped, and the FLAC is never modified. A duration that differs by more than 0.1 s is an
+error (`--allow-duration-mismatch` makes it a warning). An album is skipped if its folder already exists in the
+destination, nothing else is checked: delete the folder to redo it. Covers, `.lrc` and `booklet.pdf` are copied for
+every album, skipped ones too.
+
+**gain.** `rsgain easy -m MAX <source>`, then `rsgain easy -m MAX -p opus <dest>`. Both always run.
+
+## Long paths
+
+If `opusenc` says a path was not found, the track is copied to a short temporary path and encoded there. Such
+albums are renamed to short names for the rsgain run and renamed back. The renames are journaled; Ctrl+C and
+errors restore them. After a crash the next run refuses to start until `korg restore-names`.
+
+## Exit codes
+
+`0` ok, `1` some files failed (see `<dest>/korg-report.json`), `2` bad arguments or setup, `130` interrupted.
+Output goes to stderr; `NO_COLOR` is respected.
+
+## Development
+
+```sh
+cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
+```
+
+`tests/e2e.rs` needs `opusenc`, `rsgain`, `flac` and `lame` in `PATH` and skips itself without them.
+
+## License
+
+MIT

package/bin/korg.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Launcher: runs the native binary shipped by the matching platform package.
+// build.mjs copies this script to bin/korg.js of the launcher package.
+"use strict";
+
+const { spawn } = require("node:child_process");
+const os = require("node:os");
+const path = require("node:path");
+
+const NAME = "korg";
+
+// Candidate packages per platform, in order of preference. The musl build is fully static,
+// so on Linux (x64 and arm64) it is also a valid fallback when the glibc package was not installed.
+const PLATFORMS = {
+  "linux-x64": ["@archhaze24/korg-linux-x64", "@archhaze24/korg-linux-x64-musl"],
+  "linux-arm64": ["@archhaze24/korg-linux-arm64", "@archhaze24/korg-linux-arm64-musl"],
+  "darwin-x64": ["@archhaze24/korg-darwin-x64"],
+  "darwin-arm64": ["@archhaze24/korg-darwin-arm64"],
+  "win32-x64": ["@archhaze24/korg-win32-x64"],
+};
+
+// True on a musl-based Linux (Alpine etc.): glibc reports its version, musl does not.
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report.getReport();
+    const header = typeof report === "string" ? JSON.parse(report).header : report.header;
+    if (header && "glibcVersionRuntime" in header) return !header.glibcVersionRuntime;
+  } catch {
+    // fall through to the file check
+  }
+  try {
+    return require("node:fs").readdirSync("/lib").some((name) => name.startsWith("ld-musl-"));
+  } catch {
+    return false;
+  }
+}
+
+function binaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const candidates = PLATFORMS[key];
+  if (!candidates) {
+    throw new Error(
+      `${NAME} has no prebuilt binary for ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}. ` +
+        "Build from source instead: cargo install korg-cli",
+    );
+  }
+  const ordered = key.startsWith("linux-") && isMusl() ? [...candidates].reverse() : candidates;
+  const exe = process.platform === "win32" ? `${NAME}.exe` : NAME;
+  for (const pkg of ordered) {
+    try {
+      const manifest = require.resolve(`${pkg}/package.json`);
+      return path.join(path.dirname(manifest), "bin", exe);
+    } catch {
+      // not installed, try the next candidate
+    }
+  }
+  throw new Error(
+    `The platform package ${ordered[0]} is not installed (npm skipped the optional dependency). ` +
+      "Reinstall without --omit=optional, or run: cargo install korg-cli",
+  );
+}
+
+let binary;
+try {
+  binary = binaryPath();
+} catch (error) {
+  console.error(`${NAME}: ${error.message}`);
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+// Forward termination signals so the native process does not outlive the launcher: korg
+// restores renamed album folders when it is interrupted, so it must get the chance to run
+// its cleanup. Windows only supports SIGINT/SIGBREAK; the others are skipped.
+const FORWARDED = process.platform === "win32" ? ["SIGINT", "SIGBREAK"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+// On a POSIX terminal Ctrl-C already reaches the child through the tty (same foreground process
+// group), so SIGINT is only swallowed here (the handler keeps the launcher alive until the child
+// exits) and not forwarded a second time.
+const TTY_SIGINT = process.platform !== "win32" && process.stdin.isTTY === true;
+for (const signal of FORWARDED) {
+  process.on(signal, () => {
+    if (signal === "SIGINT" && TTY_SIGINT) return;
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  });
+}
+
+child.on("error", (error) => {
+  console.error(`${NAME}: could not run ${binary}: ${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.exit(128 + (os.constants.signals[signal] ?? 0));
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@archhaze24/korg",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Kirby's music organizer: covers, synced lyrics, FLAC to Opus, ReplayGain",
+  "keywords": [
+    "music",
+    "flac",
+    "opus",
+    "replaygain",
+    "lrc",
+    "lrclib",
+    "picard"
+  ],
+  "license": "MIT",
+  "author": "archhaze24",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archhaze24/korg.git"
+  },
+  "homepage": "https://github.com/archhaze24/korg#readme",
+  "bin": {
+    "korg": "bin/korg.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@archhaze24/korg-linux-x64": "0.1.0",
+    "@archhaze24/korg-linux-x64-musl": "0.1.0",
+    "@archhaze24/korg-linux-arm64": "0.1.0",
+    "@archhaze24/korg-linux-arm64-musl": "0.1.0",
+    "@archhaze24/korg-darwin-x64": "0.1.0",
+    "@archhaze24/korg-darwin-arm64": "0.1.0",
+    "@archhaze24/korg-win32-x64": "0.1.0"
+  }
+}