clip-join 1.0.1 → 1.0.2

package/README.md

@@ -1,66 +1,64 @@
-# ClipJoin 🎬
+<h1 align="center">ClipJoin 🎬</h1>
 
-**Merge your videos into one file: fast, lossless, and right from your terminal.**
+<p align="center"><strong>Merge your videos into one file: fast, lossless, and right from your terminal.</strong></p>
+
+<p align="center">🏆 The best, easiest way to merge your clips. No editor, no re-encoding, no fuss.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/clip-join"><img src="https://img.shields.io/npm/v/clip-join?logo=npm&color=green" alt="npm version"></a>
+  <a href="https://github.com/BrenoHA/clip-join"><img src="https://img.shields.io/badge/GitHub-BrenoHA%2Fclip--join-blue?logo=github" alt="GitHub"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/clip-join?color=blue" alt="license"></a>
+</p>
 
 > _Back from a trip with a memory card full of GoPro clips? Select them, stitch them into
-> one file, and upload the whole adventure to YouTube in one shot, public or unlisted,
-> your call._
+> one file, and upload the whole adventure to YouTube in one shot, public or unlisted, your call._
 
-Run ClipJoin, pick the files you want, reorder them, and hit join. Simple as that.
+<p align="center">
+  <img src="docs/gifs/usage-demo.gif" alt="Usage demo">
+</p>
 
-![Usage demo](docs/gifs/usage-demo.gif)
+Run ClipJoin, pick the files you want, reorder them, and hit join. Simple as that.
 
 Matching clips merge **losslessly in seconds**, with no re-encoding and no quality loss
 (40×1GB in seconds, not hours). Different formats? ClipJoin re-encodes them for you. No
 flags, no config, just a clean keyboard-driven flow from folder to finished file.
 
-## How it works
+## Install
 
-1. A short **clips-merging animation** plays on launch while ClipJoin checks for ffmpeg.
-2. **Browse** the filesystem to a folder of clips (or select individual files).
-3. Each clip's embedded `creation_time` (falling back to file mtime) sets the true
-   capture order, which you can then reorder by hand.
-4. **Toggle** clips in/out and rename the output, watching the live preview (clip
-   count, total duration, size, lossless-vs-re-encode).
-5. On join, ClipJoin first tries a **lossless concat** (`ffmpeg -c copy`), which keeps full
-   quality and works when clips share a codec/resolution. If that fails (e.g. mixed formats
-   or codecs) it **re-encodes** automatically (H.264/AAC, slower but always works).
+Install once with npm:
 
-Optionally, add a **crossfade transition** between clips (press `t` on the arrange screen).
-It's off by default; enabling it re-encodes the output (transitions can't be done losslessly).
+```bash
+npm install -g clip-join
+```
+
+> **ClipJoin uses [ffmpeg](#ffmpeg-required) on your `PATH`.** Install it before running `clipjoin` follow the steps bellow if you don't have it installed yet.
 
-Every joined file is written to a fixed **ClipJoin** folder in your home —
-`~/Movies/ClipJoin` on macOS, `~/Videos/ClipJoin` on Linux/Windows — so `clipjoin`
-saves to the same predictable place no matter which directory you run it from. Files
-get a timestamped default name (`joined_output_YYYY-MM-DD_HHMMSS.mp4`), so repeated
-joins never overwrite one another. Point it elsewhere for a run with `--out`:
+Then run it from any folder:
 
 ```bash
-clipjoin --out ~/Desktop         # write joined videos to ~/Desktop instead
+clipjoin                 # launch anywhere  (clip-join works too, same command)
 ```
 
-## Install
-
-Install globally with npm — you get a `clipjoin` command anywhere
-(`clip-join` works too, they're the same thing):
+**Just trying it out?** Run it once, no install:
 
 ```bash
-npm install -g clip-join   # then run: clipjoin
-npx clip-join              # or run once without installing
+npx clip-join
 ```
 
-**ffmpeg is required** (it bundles `ffprobe`) — install it with your package
-manager if you don't have it:
+### ffmpeg (required)
+
+ClipJoin uses **ffmpeg** (which bundles `ffprobe`). Install it with your package manager:
 
 ```bash
 brew install ffmpeg        # macOS
-sudo apt install ffmpeg    # Debian/Ubuntu
+sudo apt install ffmpeg    # Debian / Ubuntu
+winget install ffmpeg      # Windows  (or: choco install ffmpeg / scoop install ffmpeg)
 ```
 
 <details>
 <summary>Optional: one-line installer</summary>
 
-Prefer a single command that also checks Node + ffmpeg for you and fixes PATH?
+Prefer a single command that also checks Node + ffmpeg for you and fixes your PATH?
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/BrenoHA/clip-join/main/install.sh | bash
@@ -70,60 +68,62 @@ It just wraps `npm install -g clip-join` with a few pre-flight checks.
 
 </details>
 
-## Requirements
+## Where your videos are saved
 
-- **Node.js 18+**
-- **ffmpeg** (bundles `ffprobe`) on your `PATH`
+Every joined file lands in a fixed **ClipJoin** folder in your home, so it's always in the
+same predictable place no matter which directory you run `clipjoin` from:
 
-## Building from source
+- **macOS** → `~/Movies/ClipJoin`
+- **Linux / Windows** → `~/Videos/ClipJoin`
+
+Files get a timestamped default name (`joined_output_YYYY-MM-DD_HHMMSS.mp4`), so repeated
+joins never overwrite one another. Send the output somewhere else for a run with `--out`:
 
 ```bash
-git clone https://github.com/BrenoHA/clip-join.git
-cd clip-join
-npm install
-npm run build
+clipjoin --out ~/Desktop         # write joined videos to ~/Desktop instead
+clipjoin ~/clips --out ~/Desktop # start in ~/clips, save to ~/Desktop
 ```
 
+## How it works
+
+1. A short **clips-merging animation** plays on launch while ClipJoin checks for ffmpeg.
+2. **Browse** the filesystem to a folder of clips (or select individual files).
+3. Each clip's embedded `creation_time` (falling back to file mtime) sets the true
+   capture order, which you can then reorder by hand.
+4. **Toggle** clips in/out and rename the output, watching the live preview (clip
+   count, total duration, size, lossless-vs-re-encode).
+5. On join, ClipJoin first tries a **lossless concat** (`ffmpeg -c copy`), which keeps full
+   quality and works when clips share a codec/resolution. If that fails (e.g. mixed formats
+   or codecs) it **re-encodes** automatically (H.264/AAC, slower but always works).
+
+Optionally, add a **crossfade transition** between clips (press `t` on the arrange screen).
+It's off by default; enabling it re-encodes the output (transitions can't be done losslessly).
+
 ## Usage
 
+Everything is keyboard-driven.
+
 ```bash
-clipjoin                 # after installing globally
+clipjoin                 # launch and browse from the current folder
 clipjoin ~/clips         # jump straight into a folder
+clipjoin --out ~/Desktop # change where joined files are saved
+clipjoin --version       # print the installed version (alias: -v)
+```
 
-npm run dev              # dev mode from source, no build step (via tsx)
-npm start                # from source, after `npm run build`
-npm start ~/clips        # jump straight into a folder
+No need to memorize anything, every available shortcut is shown right on the
+terminal as you go, so you always know your options at each step.
 
-Everything is keyboard-driven.
+## Building from source
+
+```bash
+git clone https://github.com/BrenoHA/clip-join.git
+cd clip-join
+npm install
+npm run build            # then: npm start
+npm run dev              # or run straight from source (via tsx), no build step
+```
 
-**Browsing**
-
-| Key                          | Action                                               |
-| ---------------------------- | ---------------------------------------------------- |
-| `↑ ↓`                        | Move the cursor                                      |
-| `space` / `Enter`            | Open a directory, or select/deselect a video file    |
-| `←` / `Backspace` / `Delete` | Up a directory (cursor lands on the folder you left) |
-| `~`                          | Jump to your home directory                          |
-| `s`                          | Use every video in the current folder                |
-| `c`                          | Continue with the files you've selected              |
-| `q`                          | Quit                                                 |
-
-**Arranging & joining**
-
-Once you've picked your clips, arrange them and watch the live preview (clip count,
-total duration, size, and whether the join will be lossless):
-
-| Key               | Action                                        |
-| ----------------- | --------------------------------------------- |
-| `↑ ↓`             | Move the cursor                               |
-| `space` / `Enter` | Toggle a clip in/out of the join              |
-| `Shift+↑ ↓`       | Reorder the selected clip                     |
-| `o`               | Rename the output file (saved to the ClipJoin folder) |
-| `t`               | Toggle the transition (None / Crossfade)      |
-| `j`               | **▶ Start the join**                          |
-| `esc`             | Back to the browser                           |
-| `r`               | Join again (summary screen)                   |
-| `q`               | Quit                                          |
+Requires **Node.js 18+** and **ffmpeg** on your `PATH`.
 
 ## Project structure
 

package/dist/index.js

@@ -1,24 +1,46 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { render } from "ink";
 import { App } from "./ui/App.js";
 import { setOutputDir } from "./config.js";
+const argv = process.argv.slice(2);
+// Expand a leading `~` ourselves: Windows shells (cmd/PowerShell) don't do it,
+// so `clipjoin --out ~/Desktop` would otherwise create a literal "~" folder.
+function expandTilde(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+// `--version` / `-v`: print the package version and exit before starting the UI.
+// package.json sits one level above the built entry (dist/index.js) and is always
+// included in the npm tarball, so this resolves for global installs and dev alike.
+if (argv.includes("--version") || argv.includes("-v")) {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const { version } = JSON.parse(readFileSync(pkgPath, "utf8"));
+    console.log(version);
+    process.exit(0);
+}
 // Minimal arg parsing: one optional positional (start folder) plus `--out <dir>`
 // (aliases: `-o`, `--out=<dir>`) to redirect where joined videos are written.
 let folderArg;
-const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--out" || arg === "-o") {
         const dir = argv[++i];
         if (dir)
-            setOutputDir(dir);
+            setOutputDir(expandTilde(dir));
     }
     else if (arg.startsWith("--out=")) {
-        setOutputDir(arg.slice("--out=".length));
+        setOutputDir(expandTilde(arg.slice("--out=".length)));
     }
     else if (!arg.startsWith("-") && folderArg === undefined) {
-        folderArg = arg;
+        folderArg = expandTilde(arg);
     }
 }
 const { waitUntilExit } = render(_jsx(App, { initialFolder: folderArg }));

package/dist/ui/App.js

@@ -16,6 +16,12 @@ import { BrowseScreen } from "./screens/BrowseScreen.js";
 import { EditScreen } from "./screens/EditScreen.js";
 import { JoinScreen } from "./screens/JoinScreen.js";
 import { SummaryScreen } from "./screens/SummaryScreen.js";
+// Platform-appropriate way to install ffmpeg, shown when it's missing.
+const FFMPEG_INSTALL_HINT = process.platform === "darwin"
+    ? "brew install ffmpeg"
+    : process.platform === "win32"
+        ? "winget install ffmpeg"
+        : "sudo apt install ffmpeg";
 export function App({ initialFolder }) {
     useFullscreen();
     const { exit } = useApp();
@@ -128,7 +134,7 @@ export function App({ initialFolder }) {
     let body = null;
     switch (phase) {
         case "missingdeps":
-            body = (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: theme.danger, children: "ffmpeg / ffprobe not found on your PATH." }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: "ClipJoin needs ffmpeg to read and join videos. Install it with:" }) }), _jsx(Text, { color: theme.brand, children: " brew install ffmpeg" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.muted, children: "Press q to quit, then re-run clip-join." }) })] }));
+            body = (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: theme.danger, children: "ffmpeg / ffprobe not found on your PATH." }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: "ClipJoin needs ffmpeg to read and join videos. Install it with:" }) }), _jsxs(Text, { color: theme.brand, children: [" ", FFMPEG_INSTALL_HINT] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.muted, children: "Press q to quit, then re-run clip-join." }) })] }));
             break;
         case "browse":
             body = _jsx(BrowseScreen, { onConfirm: (files) => void beginProbe(files), onQuit: exit });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clip-join",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "ClipJoin — an interactive terminal UI for joining videos into one file.",
   "type": "module",
   "license": "MIT",