@crafter/trx 0.1.0

package/src/commands/schema.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Command } from "commander";
+import { outputJSON } from "../utils/output.ts";
+
+const SCHEMAS_DIR = join(dirname(dirname(import.meta.dir)), "schemas");
+
+const AVAILABLE_SCHEMAS = ["transcribe", "init"] as const;
+
+export function createSchemaCommand(): Command {
+	return new Command("schema")
+		.description("Introspect command schemas (agent self-service)")
+		.argument("<resource>", `Resource to describe: ${AVAILABLE_SCHEMAS.join(", ")}`)
+		.action((resource: string) => {
+			const schemaPath = join(SCHEMAS_DIR, `${resource}.json`);
+			try {
+				const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+				outputJSON(schema);
+			} catch {
+				console.error(`Unknown schema: "${resource}". Available: ${AVAILABLE_SCHEMAS.join(", ")}`);
+				process.exit(1);
+			}
+		});
+}

package/src/commands/transcribe.ts

@@ -0,0 +1,131 @@
+import { resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { Command } from "commander";
+import { type PipelineResult, runPipeline } from "../core/pipeline.ts";
+import { readConfig } from "../utils/config.ts";
+import { type OutputFormat, output, outputError } from "../utils/output.ts";
+import { validateInput, validateLanguage, validateModel } from "../validation/input.ts";
+
+function filterFields(result: PipelineResult, fields?: string): Record<string, unknown> {
+	if (!fields) return result;
+
+	const requested = fields.split(",").map((f) => f.trim());
+	const filtered: Record<string, unknown> = { success: true };
+
+	for (const field of requested) {
+		if (field === "text") filtered.text = result.text;
+		if (field === "srt") filtered.files = { srt: result.files.srt };
+		if (field === "metadata") filtered.metadata = result.metadata;
+		if (field === "files") filtered.files = result.files;
+	}
+
+	return filtered;
+}
+
+export function createTranscribeCommand(): Command {
+	return new Command("transcribe")
+		.description("Transcribe audio/video from URL or local file")
+		.argument("<input>", "URL or file path to transcribe")
+		.option("-l, --language <lang>", "language code (default: from config)")
+		.option("-m, --model <size>", "override model size")
+		.option("--fields <fields>", "limit output fields: text,srt,metadata,files")
+		.option("--dry-run", "validate input without transcribing")
+		.option("--json <payload>", "raw JSON input for agents")
+		.option("--output-dir <dir>", "output directory", ".")
+		.option("--no-download", "skip yt-dlp (input must be local)")
+		.option("--no-clean", "skip ffmpeg audio cleaning")
+		.action(async (inputArg, opts, cmd) => {
+			const format: OutputFormat = cmd.optsWithGlobals().output;
+			const isTTY = process.stdout.isTTY && format !== "json";
+
+			try {
+				const config = readConfig();
+				if (!config) {
+					outputError('No configuration found. Run "trx init" first.', format);
+					return;
+				}
+
+				let parsedInput: { type: "url" | "file"; value: string };
+				let language = opts.language;
+				let modelOverride = opts.model;
+
+				if (opts.json) {
+					const payload = JSON.parse(opts.json);
+					parsedInput = validateInput(payload.input || inputArg);
+					language = payload.language || language;
+					modelOverride = payload.model || modelOverride;
+				} else {
+					parsedInput = validateInput(inputArg);
+				}
+
+				if (language) validateLanguage(language);
+				if (modelOverride) validateModel(modelOverride);
+
+				const outputDir = resolve(opts.outputDir);
+
+				if (opts.dryRun) {
+					output(format, {
+						json: {
+							dryRun: true,
+							input: parsedInput.value,
+							inputType: parsedInput.type,
+							language: language || config.language,
+							model: modelOverride || config.modelSize,
+							outputDir,
+							steps: [
+								...(parsedInput.type === "url" && opts.download !== false ? ["download via yt-dlp"] : []),
+								...(opts.clean !== false ? ["clean audio via ffmpeg"] : []),
+								"transcribe via whisper-cli",
+								"generate .srt and .txt",
+							],
+						},
+					});
+					return;
+				}
+
+				let spinner: ReturnType<typeof p.spinner> | null = null;
+				if (isTTY) {
+					spinner = p.spinner();
+				}
+
+				const result = await runPipeline({
+					input: parsedInput.value,
+					inputType: parsedInput.type,
+					config: modelOverride
+						? {
+								...config,
+								modelSize: modelOverride,
+								modelPath: config.modelPath.replace(/ggml-\w+\.bin/, `ggml-${modelOverride}.bin`),
+							}
+						: config,
+					outputDir,
+					language,
+					noDownload: opts.download === false,
+					noClean: opts.clean === false,
+					onStep: (step) => {
+						if (spinner) spinner.start(step);
+					},
+				});
+
+				if (spinner) spinner.stop("Done");
+
+				const filtered = opts.fields ? filterFields(result, opts.fields) : result;
+				output(format, {
+					json: filtered,
+					table: {
+						headers: ["Property", "Value"],
+						rows: [
+							["Input", result.input],
+							["Language", result.metadata.language],
+							["Model", result.metadata.model],
+							["SRT", result.files.srt],
+							["TXT", result.files.txt],
+							["WAV", result.files.wav],
+						],
+					},
+				});
+			} catch (e) {
+				outputError((e as Error).message, format);
+			}
+		});
+}

package/src/core/audio.ts

@@ -0,0 +1,28 @@
+import { spawnOrThrow } from "../utils/spawn.ts";
+
+export interface AudioResult {
+	wavPath: string;
+}
+
+export async function cleanAudio(inputPath: string, outputPath: string): Promise<AudioResult> {
+	await spawnOrThrow(
+		[
+			"ffmpeg",
+			"-i",
+			inputPath,
+			"-af",
+			"silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-40dB,dynaudnorm,afftdn=nf=-25",
+			"-ar",
+			"16000",
+			"-ac",
+			"1",
+			"-c:a",
+			"pcm_s16le",
+			outputPath,
+			"-y",
+		],
+		"ffmpeg audio cleaning",
+	);
+
+	return { wavPath: outputPath };
+}

package/src/core/download.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { spawn } from "../utils/spawn.ts";
+
+export interface DownloadResult {
+	filePath: string;
+	title: string;
+}
+
+export async function downloadMedia(url: string, outputDir: string): Promise<DownloadResult> {
+	const basename = `trx-${Date.now()}`;
+	const outputTemplate = `${outputDir}/${basename}.%(ext)s`;
+
+	const result = await spawn(["yt-dlp", "--no-playlist", "-o", outputTemplate, "--print", "after_move:filepath", url]);
+
+	if (result.exitCode !== 0) {
+		throw new Error(`yt-dlp download failed: ${result.stderr}`);
+	}
+
+	const downloadedPath = result.stdout.split("\n").pop()?.trim();
+	if (!downloadedPath || !existsSync(downloadedPath)) {
+		const possibleFiles = await findDownloadedFile(outputDir, basename);
+		if (!possibleFiles) {
+			throw new Error(`Download completed but file not found. yt-dlp output: ${result.stdout}`);
+		}
+		return { filePath: possibleFiles, title: basename };
+	}
+
+	return { filePath: downloadedPath, title: basename };
+}
+
+async function findDownloadedFile(dir: string, basename: string): Promise<string | null> {
+	const glob = new Bun.Glob(`${basename}.*`);
+	for await (const file of glob.scan({ cwd: dir })) {
+		return `${dir}/${file}`;
+	}
+	return null;
+}

package/src/core/pipeline.ts

@@ -0,0 +1,71 @@
+import { basename, resolve } from "node:path";
+import type { TrxConfig } from "../utils/config.ts";
+import { cleanAudio } from "./audio.ts";
+import { downloadMedia } from "./download.ts";
+import { transcribe } from "./whisper.ts";
+
+export interface PipelineOptions {
+	input: string;
+	inputType: "url" | "file";
+	config: TrxConfig;
+	outputDir: string;
+	language?: string;
+	noDownload?: boolean;
+	noClean?: boolean;
+	onStep?: (step: string) => void;
+}
+
+export interface PipelineResult {
+	success: true;
+	input: string;
+	files: {
+		wav: string;
+		srt: string;
+		txt: string;
+	};
+	metadata: {
+		language: string;
+		model: string;
+	};
+	text: string;
+}
+
+export async function runPipeline(opts: PipelineOptions): Promise<PipelineResult> {
+	const { config, outputDir } = opts;
+	let inputFile: string;
+
+	if (opts.inputType === "url" && !opts.noDownload) {
+		opts.onStep?.("Downloading media...");
+		const downloaded = await downloadMedia(opts.input, outputDir);
+		inputFile = downloaded.filePath;
+	} else {
+		inputFile = resolve(opts.input);
+	}
+
+	const name = basename(inputFile).replace(/\.[^.]+$/, "");
+	const wavPath = resolve(outputDir, `${name}.wav`);
+
+	if (!opts.noClean) {
+		opts.onStep?.("Cleaning audio...");
+		await cleanAudio(inputFile, wavPath);
+	}
+
+	const whisperInput = opts.noClean ? inputFile : wavPath;
+	opts.onStep?.("Transcribing with Whisper...");
+	const result = await transcribe(whisperInput, config, opts.language);
+
+	return {
+		success: true,
+		input: opts.input,
+		files: {
+			wav: wavPath,
+			srt: result.srtPath,
+			txt: result.txtPath,
+		},
+		metadata: {
+			language: opts.language || config.language,
+			model: config.modelSize,
+		},
+		text: result.text,
+	};
+}

package/src/core/whisper.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { TrxConfig } from "../utils/config.ts";
+import { spawnOrThrow } from "../utils/spawn.ts";
+
+export interface WhisperResult {
+	srtPath: string;
+	txtPath: string;
+	text: string;
+}
+
+export async function transcribe(
+	wavPath: string,
+	config: TrxConfig,
+	languageOverride?: string,
+): Promise<WhisperResult> {
+	if (!existsSync(config.modelPath)) {
+		throw new Error(`Whisper model not found: ${config.modelPath}\nRun "trx init" to download a model.`);
+	}
+
+	const language = languageOverride || config.language;
+	const args = [
+		"whisper-cli",
+		"-m",
+		config.modelPath,
+		"-f",
+		wavPath,
+		"-t",
+		String(config.threads),
+		"--max-len",
+		"0",
+		"--output-srt",
+	];
+
+	if (language !== "auto") {
+		args.push("--language", language);
+	}
+
+	const flags = config.whisperFlags;
+	if (flags.suppressNst) args.push("--suppress-nst");
+	if (flags.noFallback) args.push("--no-fallback");
+	args.push("--max-context", String(flags.maxContext));
+	args.push("--entropy-thold", String(flags.entropyThold));
+	args.push("--logprob-thold", String(flags.logprobThold));
+
+	await spawnOrThrow(args, "whisper-cli transcription");
+
+	const srtPath = `${wavPath}.srt`;
+	if (!existsSync(srtPath)) {
+		throw new Error(`Whisper completed but SRT file not found: ${srtPath}`);
+	}
+
+	const srtContent = readFileSync(srtPath, "utf-8");
+	const text = srtToPlainText(srtContent);
+
+	const txtPath = wavPath.replace(/\.wav$/, ".txt");
+	await Bun.write(txtPath, text);
+
+	return { srtPath, txtPath, text };
+}
+
+function srtToPlainText(srt: string): string {
+	return srt
+		.split("\n")
+		.filter((line) => !/^\[|-->/.test(line))
+		.filter((line) => line.trim().length > 0)
+		.join("\n");
+}

package/src/utils/config.ts

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface TrxConfig {
+	modelPath: string;
+	modelSize: string;
+	language: string;
+	threads: number;
+	whisperFlags: {
+		suppressNst: boolean;
+		noFallback: boolean;
+		entropyThold: number;
+		logprobThold: number;
+		maxContext: number;
+	};
+}
+
+const TRX_DIR = join(homedir(), ".trx");
+const CONFIG_PATH = join(TRX_DIR, "config.json");
+const MODELS_DIR = join(TRX_DIR, "models");
+
+export function getTrxDir(): string {
+	return TRX_DIR;
+}
+
+export function getModelsDir(): string {
+	return MODELS_DIR;
+}
+
+export function getConfigPath(): string {
+	return CONFIG_PATH;
+}
+
+export function ensureTrxDir(): void {
+	if (!existsSync(TRX_DIR)) {
+		mkdirSync(TRX_DIR, { recursive: true });
+	}
+	if (!existsSync(MODELS_DIR)) {
+		mkdirSync(MODELS_DIR, { recursive: true });
+	}
+}
+
+export function readConfig(): TrxConfig | null {
+	if (!existsSync(CONFIG_PATH)) return null;
+	try {
+		return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as TrxConfig;
+	} catch {
+		return null;
+	}
+}
+
+export function writeConfig(config: TrxConfig): void {
+	ensureTrxDir();
+	writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export function defaultConfig(modelSize: string, language: string): TrxConfig {
+	return {
+		modelPath: join(MODELS_DIR, `ggml-${modelSize}.bin`),
+		modelSize,
+		language,
+		threads: 8,
+		whisperFlags: {
+			suppressNst: true,
+			noFallback: true,
+			entropyThold: 2.8,
+			logprobThold: -1.0,
+			maxContext: 0,
+		},
+	};
+}

package/src/utils/output.ts

@@ -0,0 +1,49 @@
+export type OutputFormat = "json" | "table" | "auto";
+
+export function outputJSON(data: unknown): void {
+	console.log(JSON.stringify(data, null, 2));
+}
+
+export function outputTable(headers: string[], rows: string[][]): void {
+	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] || "").length)));
+	const line = widths.map((w) => "-".repeat(w + 2)).join("+");
+	const formatRow = (row: string[]) => row.map((cell, i) => ` ${(cell || "").padEnd(widths[i])} `).join("|");
+
+	console.log(formatRow(headers));
+	console.log(line);
+	for (const row of rows) {
+		console.log(formatRow(row));
+	}
+}
+
+export function output(
+	format: OutputFormat,
+	data: { json: unknown; table?: { headers: string[]; rows: string[][] } },
+): void {
+	const resolved = format === "auto" ? (process.stdout.isTTY ? "table" : "json") : format;
+
+	if (resolved === "json") {
+		outputJSON(data.json);
+	} else if (data.table) {
+		outputTable(data.table.headers, data.table.rows);
+	} else {
+		outputJSON(data.json);
+	}
+}
+
+export function outputSuccess(message: string, format: OutputFormat): void {
+	if (format === "json") {
+		outputJSON({ success: true, message });
+	} else {
+		console.log(`\u2713 ${message}`);
+	}
+}
+
+export function outputError(error: string, format: OutputFormat): void {
+	if (format === "json") {
+		outputJSON({ success: false, error });
+	} else {
+		console.error(`\u2717 ${error}`);
+	}
+	process.exit(1);
+}

package/src/utils/spawn.ts

@@ -0,0 +1,27 @@
+export interface SpawnResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+}
+
+export async function spawn(cmd: string[], opts?: { cwd?: string; timeout?: number }): Promise<SpawnResult> {
+	const proc = Bun.spawn(cmd, {
+		cwd: opts?.cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+
+	const exitCode = await proc.exited;
+
+	return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+export async function spawnOrThrow(cmd: string[], context: string): Promise<string> {
+	const result = await spawn(cmd);
+	if (result.exitCode !== 0) {
+		throw new Error(`${context} failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+	}
+	return result.stdout;
+}

package/src/validation/input.ts

@@ -0,0 +1,189 @@
+import { existsSync } from "node:fs";
+
+export function rejectControlChars(input: string): string {
+	for (let i = 0; i < input.length; i++) {
+		const code = input.charCodeAt(i);
+		if (code < 0x20 && code !== 0x0a && code !== 0x0d && code !== 0x09) {
+			throw new Error(`Input contains control character at position ${i} (0x${code.toString(16)})`);
+		}
+	}
+	return input;
+}
+
+export function validateUrl(url: string): string {
+	const cleaned = rejectControlChars(url.trim());
+	if (!/^https?:\/\//i.test(cleaned)) {
+		throw new Error(`Invalid URL: must start with http:// or https://, got "${cleaned}"`);
+	}
+	if (cleaned.includes("..")) {
+		throw new Error("URL contains path traversal (..) — rejected");
+	}
+	return cleaned;
+}
+
+export function validateFilePath(path: string): string {
+	const cleaned = rejectControlChars(path.trim());
+	if (cleaned.includes("..")) {
+		throw new Error("Path contains traversal (..) — rejected");
+	}
+	if (/%[0-9a-f]{2}/i.test(cleaned)) {
+		throw new Error("Path contains URL-encoded characters — pass raw path");
+	}
+	if (!existsSync(cleaned)) {
+		throw new Error(`File not found: "${cleaned}"`);
+	}
+	return cleaned;
+}
+
+const SUPPORTED_EXTENSIONS = [".mp4", ".m4a", ".ogg", ".wav", ".webm", ".mkv", ".avi", ".mov", ".flac", ".mp3"];
+
+export function validateFileExtension(path: string): string {
+	const ext = path.slice(path.lastIndexOf(".")).toLowerCase();
+	if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+		throw new Error(`Unsupported file type: "${ext}". Supported: ${SUPPORTED_EXTENSIONS.join(", ")}`);
+	}
+	return ext;
+}
+
+const WHISPER_LANGUAGES = [
+	"auto",
+	"af",
+	"am",
+	"ar",
+	"as",
+	"az",
+	"ba",
+	"be",
+	"bg",
+	"bn",
+	"bo",
+	"br",
+	"bs",
+	"ca",
+	"cs",
+	"cy",
+	"da",
+	"de",
+	"el",
+	"en",
+	"es",
+	"et",
+	"eu",
+	"fa",
+	"fi",
+	"fo",
+	"fr",
+	"gl",
+	"gu",
+	"ha",
+	"haw",
+	"he",
+	"hi",
+	"hr",
+	"ht",
+	"hu",
+	"hy",
+	"id",
+	"is",
+	"it",
+	"ja",
+	"jw",
+	"ka",
+	"kk",
+	"km",
+	"kn",
+	"ko",
+	"la",
+	"lb",
+	"ln",
+	"lo",
+	"lt",
+	"lv",
+	"mg",
+	"mi",
+	"mk",
+	"ml",
+	"mn",
+	"mr",
+	"ms",
+	"mt",
+	"my",
+	"ne",
+	"nl",
+	"nn",
+	"no",
+	"oc",
+	"pa",
+	"pl",
+	"ps",
+	"pt",
+	"ro",
+	"ru",
+	"sa",
+	"sd",
+	"si",
+	"sk",
+	"sl",
+	"sn",
+	"so",
+	"sq",
+	"sr",
+	"su",
+	"sv",
+	"sw",
+	"ta",
+	"te",
+	"tg",
+	"th",
+	"tk",
+	"tl",
+	"tr",
+	"tt",
+	"uk",
+	"ur",
+	"uz",
+	"vi",
+	"yi",
+	"yo",
+	"zh",
+] as const;
+
+export type WhisperLanguage = (typeof WHISPER_LANGUAGES)[number];
+
+export function validateLanguage(lang: string): WhisperLanguage {
+	const cleaned = lang.trim().toLowerCase();
+	if (!WHISPER_LANGUAGES.includes(cleaned as WhisperLanguage)) {
+		throw new Error(`Unsupported language: "${lang}". Use ISO 639-1 code or "auto".`);
+	}
+	return cleaned as WhisperLanguage;
+}
+
+const VALID_MODELS = [
+	"tiny",
+	"tiny.en",
+	"base",
+	"base.en",
+	"small",
+	"small.en",
+	"medium",
+	"medium.en",
+	"large",
+] as const;
+export type WhisperModel = (typeof VALID_MODELS)[number];
+
+export function validateModel(model: string): WhisperModel {
+	const cleaned = model.trim().toLowerCase();
+	if (!VALID_MODELS.includes(cleaned as WhisperModel)) {
+		throw new Error(`Unknown model: "${model}". Available: ${VALID_MODELS.join(", ")}`);
+	}
+	return cleaned as WhisperModel;
+}
+
+export function validateInput(input: string): { type: "url" | "file"; value: string } {
+	const cleaned = rejectControlChars(input.trim());
+	if (/^https?:\/\//i.test(cleaned)) {
+		return { type: "url", value: validateUrl(cleaned) };
+	}
+	validateFilePath(cleaned);
+	return { type: "file", value: cleaned };
+}