clip-join 1.0.0 → 1.0.2

package/README.md

@@ -1,116 +1,129 @@
-# 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).
-
-Every joined file is written to the **`output/`** folder with a timestamped default
-name (`joined_output_YYYY-MM-DD_HHMMSS.mp4`), so repeated joins never overwrite one another.
+```bash
+npm install -g clip-join
+```
 
-## Install
+> **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.
 
-The fastest way — one line, and you get a global `clipjoin` command
-(`clip-join` works too, they're the same thing):
+Then run it from any folder:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/BrenoHA/clip-join/main/install.sh | bash
+clipjoin                 # launch anywhere  (clip-join works too, same command)
 ```
 
-The installer checks for Node and ffmpeg (guiding you if either is missing), then
-installs ClipJoin globally. Prefer to do it yourself? Any of these also work:
+**Just trying it out?** Run it once, no install:
 
 ```bash
-npm install -g clip-join   # global `clipjoin` (or `clip-join`) command
-npx clip-join              # run once without installing
+npx clip-join
 ```
 
-**ffmpeg is still 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)
 ```
 
-## Requirements
+<details>
+<summary>Optional: one-line installer</summary>
 
-- **Node.js 18+**
-- **ffmpeg** (bundles `ffprobe`) on your `PATH`
+Prefer a single command that also checks Node + ffmpeg for you and fixes your PATH?
 
-## Building from source
+```bash
+curl -fsSL https://raw.githubusercontent.com/BrenoHA/clip-join/main/install.sh | bash
+```
+
+It just wraps `npm install -g clip-join` with a few pre-flight checks.
+
+</details>
+
+## Where your videos are saved
+
+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:
+
+- **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 into `output/`) |
-| `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
 
@@ -165,8 +178,8 @@ conventions, and the PR process.
   slightly different per-clip encoding perfectly. If playback looks off, the clips likely
   need re-encoding (ClipJoin falls back automatically when stream copy fails).
 - **Original files are never modified or deleted.**
-- Output names are always confined to `output/` (a path typed into the rename field is
-  reduced to its basename).
+- Output names are always confined to the output folder (a path typed into the rename
+  field is reduced to its basename); use `--out <dir>` to change the folder itself.
 
 ## License
 

package/dist/config.js

@@ -1,3 +1,4 @@
+import os from "node:os";
 import path from "node:path";
 export const DEFAULT_EXTS = ["mp4", "mov", "m4v", "avi", "mkv"];
 /**
@@ -11,8 +12,27 @@ export const TRANSITIONS = [
     { id: "none", label: "None" },
     { id: "crossfade", label: "Crossfade", xfade: "fade" },
 ];
-/** Every joined video is written here, relative to where ClipJoin is launched. */
-export const OUTPUT_DIR = path.resolve(process.cwd(), "output");
+/**
+ * Default home for joined videos: a fixed, always-writable folder under the
+ * user's home so `clipjoin` behaves identically from any directory (rather than
+ * scattering `output/` folders wherever it happens to be launched).
+ *   macOS → ~/Movies/ClipJoin   ·   Linux/Windows → ~/Videos/ClipJoin
+ */
+export function defaultOutputDir() {
+    const parent = process.platform === "darwin" ? "Movies" : "Videos";
+    return path.join(os.homedir(), parent, "ClipJoin");
+}
+// The active output directory. Defaults per-platform; overridden at startup by
+// the `--out <dir>` flag via setOutputDir().
+let outputDir = defaultOutputDir();
+/** Absolute directory every joined video (and its chapters file) is written to. */
+export function getOutputDir() {
+    return outputDir;
+}
+/** Point output at a specific directory (from `--out`). Resolved to absolute. */
+export function setOutputDir(dir) {
+    outputDir = path.resolve(dir);
+}
 export const REENCODE_CRF = 18;
 export const REENCODE_PRESET = "veryfast";
 /**

package/dist/core/output.js

@@ -1,21 +1,21 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { OUTPUT_DIR, defaultOutputName } from "../config.js";
+import { getOutputDir, defaultOutputName } from "../config.js";
 import { humanClock } from "./format.js";
 /**
- * Resolve a user-supplied name to an absolute path inside OUTPUT_DIR. Only the
- * basename is honored, so "../evil.mp4" or an absolute path can't escape output/.
+ * Resolve a user-supplied name to an absolute path inside the output dir. Only
+ * the basename is honored, so "../evil.mp4" or an absolute path can't escape it.
  */
 export function resolveOutputPath(name) {
     let base = path.basename(name.trim());
     // basename() strips separators; "." / ".." would still resolve to or above
-    // OUTPUT_DIR, so fall back to the default for those (and for an empty name).
+    // the output dir, so fall back to the default for those (and for an empty name).
     if (!base || base === "." || base === "..")
         base = defaultOutputName();
-    return path.join(OUTPUT_DIR, base);
+    return path.join(getOutputDir(), base);
 }
 export async function ensureOutputDir() {
-    await fs.mkdir(OUTPUT_DIR, { recursive: true });
+    await fs.mkdir(getOutputDir(), { recursive: true });
 }
 /** Build the line-per-chapter text content for the given (included) clips. */
 function buildChaptersContent(clips) {

package/dist/index.js

@@ -1,7 +1,47 @@
 #!/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";
-const folderArg = process.argv[2];
+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;
+for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--out" || arg === "-o") {
+        const dir = argv[++i];
+        if (dir)
+            setOutputDir(expandTilde(dir));
+    }
+    else if (arg.startsWith("--out=")) {
+        setOutputDir(expandTilde(arg.slice("--out=".length)));
+    }
+    else if (!arg.startsWith("-") && folderArg === undefined) {
+        folderArg = expandTilde(arg);
+    }
+}
 const { waitUntilExit } = render(_jsx(App, { initialFolder: folderArg }));
 await waitUntilExit();

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.0",
+  "version": "1.0.2",
   "description": "ClipJoin — an interactive terminal UI for joining videos into one file.",
   "type": "module",
   "license": "MIT",