@petercjl/seedaudiocli 0.2.0 → 0.3.0

package/npm/cli.mjs

@@ -8,9 +8,10 @@ import { source, targetPath, status, install } from './skills.mjs';
 const args = process.argv.slice(2);
 const print = value => console.log(JSON.stringify(value, null, 2));
 const flag = name => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+const manifest = JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
 try {
   if (await beforeRun(args)) { /* child completed */ }
-  else if (['version', '--version'].includes(args[0])) console.log(`seedaudiocli ${pkg.version}`);
+  else if (['version', '--version'].includes(args[0])) args.includes('--json') ? print({ok:true,package:pkg.name,version:pkg.version}) : console.log(`seedaudiocli ${pkg.version}`);
   else if (args[0] === 'capabilities') print(JSON.parse(fs.readFileSync(path.join(root, 'capabilities.json'), 'utf8')));
   else if (args[0] === 'doctor') {
     const python = findPython();
@@ -20,19 +21,42 @@ try {
     print({ ok: auth.status === 0, version: pkg.version, python, skill_source: source, config });
     process.exitCode = auth.status === 0 ? 0 : 1;
   } else if (args[0] === 'skill') {
-    if (args[1] === 'source') print({ ok: true, source, version: pkg.version });
+    if(args.includes('--help')||args.includes('-h')) {
+      print(manifest.commandContracts['skill '+args[1]]||{error:'Unknown Skill command'});
+      process.exit(0);
+    }
+    const boolean = new Set(['--json','--all']);
+    const values = new Set(['--agent','--root','--name']);
+    const seen = new Set();
+    for(let i=2;i<args.length;i++) {
+      const a=args[i];
+      if(seen.has(a)||(!boolean.has(a)&&!values.has(a))) throw fail('INVALID_ARGUMENT','Unknown or duplicate Skill option.');
+      seen.add(a);
+      if(values.has(a)&&(!args[++i]||args[i].startsWith('--'))) throw fail('INVALID_ARGUMENT','Skill option requires a value.');
+    }
+    if(flag('--name') && flag('--name')!=='seedaudiocli') throw fail('SKILL_NOT_FOUND','Unknown logical Skill.');
+    const identity = {...manifest,ok:true,name:'seedaudiocli',package:pkg.name,source,version:pkg.version};
+    if (args[1] === 'source') print(args.includes('--all') ? {...identity,complete:true,skills:[identity]} : identity);
     else {
-      const target = targetPath(flag('--agent') || 'codex', flag('--root'));
-      if (args[1] === 'status') print({ ok: true, ...status(target), record: undefined });
+      const target = targetPath(flag('--agent') || 'generic', flag('--root'));
+      if (args[1] === 'status') {
+        const state=status(target);
+        print({...identity,...state,version:state.version||pkg.version,edited:!!state.edited,verification:{verified:!!state.current,algorithm:'sha256'},recovery:{required:false},record:undefined});
+      }
       else if (['install', 'update'].includes(args[1])) print(install(target));
       else throw fail('INVALID_COMMAND', 'Use skill source|status|install|update.');
     }
   } else if (args[0] === 'update') {
     const check = await checkUpdate();
-    if (args[1] === 'install' && check.updateAvailable) print(installUpdate(check));
-    else print({ ...check, policy: 'before-every-run', opt_out: 'SEEDAUDIO_AUTO_UPDATE=0' });
+    if(args[1]==='install') {
+      const target=targetPath(flag('--agent')||'generic',flag('--root'));
+      if(!check.ok) throw fail('REGISTRY_UNAVAILABLE','Keep current installation; update version could not be checked.');
+      print(check.updateAvailable ? installUpdate(check,{target}) : {...install(target),package_changed:false});
+    } else if(args[1]==='check') print({ ...check, policy: 'cached-notify', opt_out: 'SEEDAUDIO_AUTO_UPDATE=0' });
+    else throw fail('INVALID_COMMAND','Use update check|install.');
   } else if (!args.length || ['--help', '-h'].includes(args[0])) {
-    console.log('seedaudiocli: setup | config import FILE [--replace] | auth status | generate | task | payload\nPackage: version | capabilities --json | doctor --json | skill source/status/install/update [--agent codex|sealseek] [--root SKILLS_DIRECTORY] | update check/install\nRuntime: Node.js 22+, Python 3.9+ (SEEDAUDIO_PYTHON optional).');
+    if(args.includes('--json')){print(manifest);process.exit(0);}
+    console.log('seedaudiocli: setup | config import FILE [--replace] | auth status | voice | generate | task | payload\nPackage: version [--json] | capabilities --json | doctor --json | skill source/status/install/update [--agent NAME] [--root ABSOLUTE_SKILLS_DIRECTORY] | update check/install\nRuntime: Node.js 22+, Python 3.9+ (SEEDAUDIO_PYTHON optional).');
     process.exitCode = runPython(['--help']).status || 0;
   } else {
     const result = runPython(args);

package/npm/notice.mjs

@@ -0,0 +1 @@
+console.error('seedaudiocli: npm runtime installed. The current Agent must resolve its own Skill directory and follow INSTALL.md / UPDATE.md to synchronize and verify the companion Skill. User credentials and voice library are preserved.');

package/npm/skills.mjs

@@ -5,15 +5,16 @@ import crypto from 'node:crypto';
 import { stateRoot } from './update.mjs';
 import { root, pkg, fail } from './runtime.mjs';
 
-export const source = path.join(root, 'skills', 'seedaudiocli');
+export const source = fs.existsSync(path.join(root, 'skills', 'seedaudiocli')) ? path.join(root, 'skills', 'seedaudiocli') : path.dirname(root);
 const marker = '.seedaudiocli-managed.json';
 const metadata = 'agents/openai.yaml';
 function exists(file) { try { return fs.lstatSync(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
-export function inventory(dir) {
+export function inventory(dir, skipRuntime = false) {
   const result = {};
   function walk(at, prefix = '') {
     for (const entry of fs.readdirSync(at, { withFileTypes: true })) {
       if (entry.name === marker) continue;
+      if (skipRuntime && !prefix && entry.name === 'runtime') continue;
       const relative = prefix + entry.name;
       if (entry.isSymbolicLink()) throw fail('SKILL_UNSAFE_TARGET', 'Skill files must not contain symlinks.');
       if (entry.isDirectory()) walk(path.join(at, entry.name), relative + '/');
@@ -24,13 +25,21 @@ export function inventory(dir) {
   return result;
 }
 export function targetPath(agent, targetRoot) {
-  if (!['codex', 'sealseek'].includes(agent)) throw fail('INVALID_AGENT', 'Choose --agent codex or sealseek.');
-  let base = targetRoot;
-  if (!base && agent === 'codex') base = path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills');
-  if (!base && agent === 'sealseek') base = process.env.SEALSEEK_SKILLS_DIR;
-  if (!base) throw fail('AGENT_PATH_REQUIRED', 'Provide the actual SealSeek skills directory through --root or SEALSEEK_SKILLS_DIR.');
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(agent)) throw fail('INVALID_AGENT', 'Agent names use lowercase letters, digits and hyphens.');
+  const base = targetRoot;
+  if (!base) throw fail('AGENT_PATH_REQUIRED', 'Resolve the current Agent Skill directory and pass it explicitly through --root.');
+  if (!path.isAbsolute(base)) throw fail('AGENT_PATH_REQUIRED', '--root must be an absolute Skill parent directory.');
   return path.join(path.resolve(base), 'seedaudiocli');
 }
+export function expectedFiles() {
+  const files = inventory(source, true);
+  for (const folder of ['npm', 'seedaudiocli']) for (const file of fs.readdirSync(path.join(root, folder))) {
+    if (!file.endsWith(folder === 'npm' ? '.mjs' : '.py')) continue;
+    files[`runtime/${folder}/${file}`] = crypto.createHash('sha256').update(fs.readFileSync(path.join(root, folder, file))).digest('hex');
+  }
+  for (const file of ['package.json', 'capabilities.json']) files[`runtime/${file}`] = crypto.createHash('sha256').update(fs.readFileSync(path.join(root, file))).digest('hex');
+  return files;
+}
 export function status(target) {
   const st = exists(target);
   if (!st) return { installed: false, managed: false, current: false, target };
@@ -41,8 +50,8 @@ export function status(target) {
   if (Object.keys(record.files).some(file => !file || path.isAbsolute(file) || file.includes('\\') || file.split('/').some(part => ['.', '..', ''].includes(part)))) throw fail('SKILL_UNSAFE_TARGET', 'Invalid managed-file path in Skill ownership record.');
   const files = inventory(target);
   const edited = Object.entries(record.files).some(([file, hash]) => file !== metadata && files[file] !== hash);
-  const expected = inventory(source);
-  const current = !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
+  const expected = expectedFiles();
+  const current = !edited && record.version === pkg.version && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
   return { installed: true, managed: true, current, edited, target, version: record.version, record };
 }
 export function install(target) {
@@ -54,7 +63,7 @@ export function install(target) {
   if (state.installed && !state.managed) throw fail('SKILL_UNMANAGED', 'An existing user-owned Skill occupies this target; preserve it and choose a new root or explicitly migrate it.');
   if (state.edited) throw fail('SKILL_EDITED', 'Managed Skill files contain local edits; preserve and reconcile those edits before updating.');
   if (state.current && state.version === pkg.version) return { ...state, record: undefined, ok: true, changed: false };
-  const expected = inventory(source);
+  const expected = expectedFiles();
   for (const file of Object.keys(expected)) {
     if (state.installed && exists(path.join(target, file)) && !(file in state.record.files) && file !== metadata) throw fail('SKILL_UNMANAGED_FILE', 'A new bundled file would overwrite a user-owned file.');
   }
@@ -73,7 +82,7 @@ export function install(target) {
     for (const file of Object.keys(expected)) {
       if (file === metadata && exists(path.join(target, file))) continue;
       fs.mkdirSync(path.dirname(path.join(target, file)), { recursive: true });
-      fs.copyFileSync(path.join(source, file), path.join(target, file));
+      fs.copyFileSync(file.startsWith('runtime/') ? path.join(root, file.slice(8)) : path.join(source, file), path.join(target, file));
     }
     for (const file of Object.keys(state.record?.files || {})) {
       if (file !== metadata && !(file in expected)) fs.unlinkSync(path.join(target, file));
@@ -81,7 +90,7 @@ export function install(target) {
     const actual = inventory(target);
     if (Object.entries(expected).some(([file, hash]) => file !== metadata && actual[file] !== hash)) throw fail('SKILL_VERIFY_FAILED', 'Installed Skill hashes differ from the package.');
     fs.writeFileSync(path.join(target, marker), JSON.stringify({ package: pkg.name, version: pkg.version, files: expected }, null, 2));
-    return { ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
+    return { ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null, runtime_entry: path.join(target,'runtime','npm','cli.mjs'), host_discovery: 'pending-host-verification' };
   } catch (e) {
     throw fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`);
   } finally { fs.closeSync(lockfd); fs.unlinkSync(lock); }

package/npm/update.mjs

@@ -20,7 +20,7 @@ export function globalPrefix(location=root, platform=process.platform) {
 }
 export async function checkUpdate(registry=fetch) {
   try {
-    const r=await registry(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/latest`,{signal:AbortSignal.timeout(8000)});
+    const r=await registry(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/latest`,{signal:AbortSignal.timeout(4000)});
     if(!r.ok) throw Error('Registry unavailable');
     const data=await r.json();
     if(data.name!==pkg.name || !/^\d+\.\d+\.\d+$/.test(data.version)) throw Error('Invalid stable package');
@@ -40,6 +40,7 @@ function npm(args) {
   return r.stdout;
 }
 export function installUpdate(check, services={}) {
+  if(!services.target) throw fail('AGENT_PATH_REQUIRED','Resolve one current Agent Skill target before package replacement.');
   const prefix=services.prefix || globalPrefix();
   if(!prefix) throw fail('UPDATE_OWNER_REQUIRED','This installation is managed by its source checkout or parent package.');
   const state=stateRoot(); fs.mkdirSync(state,{recursive:true});
@@ -54,15 +55,15 @@ export function installUpdate(check, services={}) {
     if(!newer(check.available,live.version)) return {ok:true,changed:false,version:live.version};
     fs.mkdirSync(backup,{recursive:true});
     const archive=JSON.parse(run(['pack',root,'--ignore-scripts','--pack-destination',backup,'--json']))[0];
-    const registered=path.join(state,'skill-targets');
-    const known=[path.join(process.env.CODEX_HOME || path.join(os.homedir(),'.codex'),'skills','seedaudiocli')];
-    for(const f of (fs.existsSync(registered) ? fs.readdirSync(registered) : [])) {
-      try { known.push(JSON.parse(fs.readFileSync(path.join(registered,f),'utf8')).target); } catch { /* invalid registration */ }
-    }
-    for(const target of new Set(known)) {
-      try { if(JSON.parse(fs.readFileSync(path.join(target,'.seedaudiocli-managed.json'),'utf8')).package===pkg.name) targets.push(target); } catch { /* unmanaged or absent */ }
-    }
     const entry=path.join(root,'npm','cli.mjs');
+    const target=services.target;
+    if(fs.existsSync(target)) {
+      const pre=spawn(process.execPath,[entry,'skill','status','--root',path.dirname(target),'--json'],{encoding:'utf8',env:{...process.env,SEEDAUDIO_AUTO_UPDATE:'0'}});
+      let info;try{info=JSON.parse(pre.stdout);}catch{throw fail('SKILL_PREFLIGHT_FAILED','Cannot verify selected Skill before package replacement.');}
+      if(!info.managed||info.edited)throw fail('SKILL_EDITED','Preserve unmanaged or edited Skill before update.');
+      fs.cpSync(target,path.join(backup,'skill'),{recursive:true,errorOnExist:true,force:false});
+    }
+    targets.push(target);
     const sync=target=>spawn(process.execPath,[entry,'skill','update','--root',path.dirname(target)],{encoding:'utf8',timeout:30000,env:{...process.env,SEEDAUDIO_AUTO_UPDATE:'0'}});
     let mutated=false;
     try {
@@ -83,19 +84,30 @@ export function installUpdate(check, services={}) {
   } finally { fs.rmdirSync(lock); }
 }
 export async function beforeRun(args, services={}) {
-  if(process.env.SEEDAUDIO_AUTO_UPDATE==='0' || !globalPrefix() || args[0]==='update') return false;
+  if(process.env.SEEDAUDIO_AUTO_UPDATE==='0' || !globalPrefix() || !['generate'].includes(args[0]) || args.includes('--dry-run') || args.includes('--help')) return false;
+  // Detection only: installations reconcile one explicitly selected host.
+  const cache=path.join(stateRoot(),'update-check.json');
+  try {
+    const info=JSON.parse(fs.readFileSync(cache,'utf8'));
+    if(Number.isFinite(info.checkedAt) && Date.now()-info.checkedAt<86400000)return false;
+  } catch { /* absent/corrupt cache is never overwritten */ }
+  let fd;
+  const guard=cache+'.lock';
+  try {fs.mkdirSync(path.dirname(cache),{recursive:true});fd=fs.openSync(guard,'wx',0o600);} catch {return false;}
+  try {
   const check=await (services.check || checkUpdate)();
-  if(!check.ok) console.error('[seedaudiocli] Update check unavailable; using installed version.');
-  if(!check.updateAvailable) return false;
+  if(check.updateAvailable)console.error(`[seedaudiocli] ${check.available} is available; ask the current Agent to update CLI and its own Skill.`);
   try {
-    const result=(services.install || installUpdate)(check);
-    console.error(`[seedaudiocli] Using latest ${result.version}.`);
-  } catch(e) {
-    if(['UPDATE_BUSY','ROLLBACK_SYNC_REQUIRED','ROLLBACK_REQUIRED'].includes(e.code)) throw e;
-    console.error(`[seedaudiocli] ${e.code || 'UPDATE_FAILED'}; using restored installed version.`);
-  }
-  // Delegate once only after update/rollback; never replay a business request.
-  const r=spawnSync(process.execPath,[path.join(root,'npm','cli.mjs'),...args],{stdio:'inherit',env:{...process.env,SEEDAUDIO_AUTO_UPDATE:'0'}});
-  process.exitCode=r.status??1;
-  return true;
+    fs.mkdirSync(path.dirname(cache),{recursive:true});
+    if(!fs.existsSync(cache))fs.writeFileSync(cache,JSON.stringify({checkedAt:Date.now(),check}),{flag:'wx',mode:0o600});
+    else {
+      const old=JSON.parse(fs.readFileSync(cache,'utf8'));
+      if(Number.isFinite(old.checkedAt)) {
+        const next=cache+'.'+crypto.randomUUID();
+        fs.writeFileSync(next,JSON.stringify({checkedAt:Date.now(),check}),{flag:'wx',mode:0o600});fs.renameSync(next,cache);
+      }
+    }
+  } catch { /* cache must not block business execution */ }
+  } finally {fs.closeSync(fd);fs.unlinkSync(guard);}
+  return false;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/seedaudiocli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Seed Audio CLI with portable Agent skill and persistent user credentials",
   "type": "module",
   "bin": {
@@ -14,7 +14,10 @@
     "adapters/",
     "seedaudiocli.env.example",
     "seedaudiocli.config.example.json",
-    "README.md"
+    "README.md",
+    "INSTALL.md",
+    "UPDATE.md",
+    "scripts/validate-release.mjs"
   ],
   "engines": {
     "node": ">=22"
@@ -22,7 +25,8 @@
   "scripts": {
     "check": "node --check npm/cli.mjs && node --check npm/runtime.mjs && node --check npm/skills.mjs",
     "test": "node --test test/*.test.mjs",
-    "prepack": "npm run check && npm test"
+    "prepack": "npm run check && npm test && node scripts/validate-release.mjs",
+    "postinstall": "node npm/notice.mjs"
   },
   "publishConfig": {
     "access": "public"

package/scripts/validate-release.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import {pkg,root,runPython} from '../npm/runtime.mjs';
+import path from 'node:path';
+
+const result=runPython(['--version'],{encoding:'utf8',stdio:'pipe'});
+assert.equal(result.status,0);
+assert.equal(result.stdout.trim(),`seedaudiocli ${pkg.version}`);
+const source=fs.readFileSync(path.join(root,'skills/seedaudiocli/SKILL.md'),'utf8');
+assert.ok(source.includes('--voice'));
+const m=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json')));
+assert.ok(m.voiceLibrary);
+assert.equal(m.installationLifecycle.sharedLinksAllowed,false);
+console.log(JSON.stringify({ok:true,version:pkg.version,pythonVersionMatches:true,voiceContract:true}));

package/seedaudiocli/cli.py

@@ -13,6 +13,7 @@ from typing import Any
 
 from . import __version__
 from . import official
+from . import voices
 from .config import (
     DEFAULT_BASE_URL,
     DEFAULT_MODEL,
@@ -34,6 +35,7 @@ def print_json(data: Any) -> None:
 
 
 def add_generation_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--voice", help="Named local voice ID/name, optionally NAME@VERSION; prompt is narration text.")
     parser.add_argument("--prompt", help="Prompt text, max 3000 characters.")
     parser.add_argument("--prompt-file", help="Path to a UTF-8 prompt text file.")
     parser.add_argument("--model", help="Override model id. Default: seed-audio-1.0.")
@@ -53,6 +55,8 @@ def add_generation_args(parser: argparse.ArgumentParser) -> None:
 
 def generation_payload_from_args(args: argparse.Namespace) -> dict[str, Any]:
     prompt = read_prompt(args.prompt, args.prompt_file)
+    if args.voice:
+        return voices.apply(args, prompt)
     audio_refs = list(getattr(args, "audio_reference", None) or [])
     image_urls = list(getattr(args, "image_url", None) or [])
     return build_payload(
@@ -84,7 +88,7 @@ def submit_or_print(payload, args):
         raise ValueError("download destination must be a directory.")
     if args.dry_run:
         print_json({"ok": True, "dry_run": True, "request_hash": h, "payload": payload,
-                    "provider": "Volcengine", "endpoint": DEFAULT_BASE_URL + "/api/v3/tts/create"})
+                    "voice": getattr(args, "voice_receipt", None), "provider": "Volcengine", "endpoint": DEFAULT_BASE_URL + "/api/v3/tts/create"})
         return 0
     seedaudio_base_url()
     key = seedaudio_api_key()
@@ -108,6 +112,8 @@ def submit_or_print(payload, args):
             job_dir(task_id).mkdir(mode=0o700)
             record = {"task_id": task_id, "request_id": task_id, "request_hash": h, "provider": "Volcengine",
                       "status": "submitting", "created_at": time.time(), "format": payload.get("audio_config", {}).get("format", "wav")}
+            if getattr(args, "voice_receipt", None):
+                record["voice"] = args.voice_receipt
             save_record(record)
             # Persist the local ID before sending the only billable request.
             print(json.dumps({"event": "submitting", "task_id": task_id}), file=sys.stderr, flush=True)
@@ -124,6 +130,8 @@ def submit_or_print(payload, args):
             result = {"ok": True, "task_id": task_id, "job": record}
         if args.download:
             result["downloaded_to"] = export_audio(record, args.download, args.output_name)
+        if getattr(args, "voice_receipt", None):
+            result["voice"] = args.voice_receipt
         print_json(result)
         return 0
     finally:
@@ -200,14 +208,33 @@ def cmd_models(_: argparse.Namespace) -> int:
 
 
 def cmd_generate(args: argparse.Namespace) -> int:
-    if args.generate_cmd == "audio-ref" and not (args.audio_reference or args.audio_file):
-        raise ValueError("audio-ref requires --audio-reference or --audio-file.")
+    if args.generate_cmd == "audio-ref" and not (args.audio_reference or args.audio_file or args.voice):
+        raise ValueError("audio-ref requires --voice, --audio-reference or --audio-file.")
     if args.generate_cmd == "image-ref" and not (args.image_url or args.image_file):
         raise ValueError("image-ref requires --image-url or --image-file.")
     payload = generation_payload_from_args(args)
     return submit_or_print(payload, args)
 
 
+def cmd_voice(args):
+    if args.voice_cmd == "list":
+        items = voices.profiles()
+        if not args.all:
+            items = [max([q for q in items if q["id"] == identity], key=lambda q: q["version"]) for identity in sorted({q["id"] for q in items})]
+        result = {"ok": True, "library": str(voices.library()), "voices": items}
+    elif args.voice_cmd == "save":
+        result = voices.save(args)
+    elif args.voice_cmd == "export":
+        result = voices.export_voice(args.selector, args.output)
+    elif args.voice_cmd == "import":
+        result = voices.import_voice(args.file)
+    else:
+        p, sample = voices.get(args.selector)
+        result = {"ok": True, "voice": p, "reference_path": str(sample), "preview_path": str(sample), "paid": False}
+    print_json(result)
+    return 0
+
+
 def cmd_task(args):
     if args.task_cmd == "jobs":
         if args.limit < 1:
@@ -280,6 +307,34 @@ def build_parser() -> argparse.ArgumentParser:
     models_list = models_sub.add_parser("list", help="List built-in model ids.")
     models_list.set_defaults(func=cmd_models)
 
+    voice = sub.add_parser("voice", help="Private named voice library; local operations do not generate audio.")
+    voice_sub = voice.add_subparsers(dest="voice_cmd", required=True)
+    voice_list = voice_sub.add_parser("list", help="List latest revisions; --all includes history.")
+    voice_list.add_argument("--all", action="store_true")
+    for action in ["show", "preview"]:
+        leaf = voice_sub.add_parser(action, help="Inspect settings and return the existing sample for playback.")
+        leaf.add_argument("selector")
+        leaf.set_defaults(func=cmd_voice)
+    voice_save = voice_sub.add_parser("save", help="Copy a reference and settings into a new immutable revision.")
+    voice_save.add_argument("--id", required=True)
+    voice_save.add_argument("--name", required=True)
+    voice_save.add_argument("--audio-file", required=True)
+    voice_save.add_argument("--description", default="")
+    voice_save.add_argument("--style", default="")
+    voice_save.add_argument("--model", default="seed-audio-1.0")
+    voice_save.add_argument("--format", choices=["wav", "mp3", "pcm", "ogg_opus"], default="mp3")
+    voice_save.add_argument("--sample-rate", type=int, default=24000)
+    voice_save.add_argument("--speech-rate", type=int, default=0)
+    voice_save.add_argument("--pitch-rate", type=int, default=0)
+    voice_save.add_argument("--loudness-rate", type=int)
+    voice_export = voice_sub.add_parser("export", help="Export one self-contained voice bundle with its sample.")
+    voice_export.add_argument("selector")
+    voice_export.add_argument("--output", required=True)
+    voice_import = voice_sub.add_parser("import", help="Validate and import a voice bundle as a new local revision.")
+    voice_import.add_argument("file")
+    for leaf in [voice_list, voice_save, voice_export, voice_import]:
+        leaf.set_defaults(func=cmd_voice)
+
     generate = sub.add_parser("generate", help="Create Seed-Audio generation tasks.")
     gen_sub = generate.add_subparsers(dest="generate_cmd", required=True)
 
@@ -348,6 +403,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
+    argv = [x for x in (sys.argv[1:] if argv is None else argv) if x != "--json"]
     args = parser.parse_args(argv)
     try:
         network = ((args.cmd == "generate" and not args.dry_run)

package/seedaudiocli/voices.py

@@ -0,0 +1,229 @@
+"""Private, immutable named voice presets. No provider calls or shared samples."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+import wave
+from pathlib import Path
+
+from .config import config_path
+from .payloads import build_payload, validate_payload
+
+MAX_BYTES = 10 * 1024 * 1024
+SETTINGS = {"model", "format", "sample_rate", "speech_rate", "pitch_rate", "loudness_rate"}
+
+
+class VoiceError(ValueError):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+
+
+def library():
+    return Path(os.environ.get("SEEDAUDIO_VOICE_DIR", str(config_path().parent / "voices"))).expanduser().absolute()
+
+
+def regular(path):
+    if path.is_symlink() or not path.is_file():
+        raise VoiceError("VOICE_UNSAFE_FILE", "Expected a regular, non-symlink file.")
+    if not 0 < path.stat().st_size <= MAX_BYTES * 2:
+        raise VoiceError("VOICE_INVALID", "Voice file is empty or exceeds the size limit.")
+
+
+def audio_seconds(path):
+    regular(path)
+    if path.stat().st_size > MAX_BYTES or path.suffix.lower() not in {".wav", ".mp3", ".ogg", ".opus"}:
+        raise VoiceError("VOICE_INVALID", "Reference must be WAV, MP3 or Ogg/Opus, up to 10 MiB.")
+    if path.suffix.lower() == ".wav":
+        try:
+            with wave.open(str(path), "rb") as audio:
+                seconds = audio.getnframes() / audio.getframerate()
+        except (wave.Error, EOFError, ZeroDivisionError):
+            raise VoiceError("VOICE_INVALID", "Reference WAV is invalid.") from None
+    else:
+        probe = shutil.which("ffprobe")
+        if not probe:
+            raise VoiceError("VOICE_PROBE_REQUIRED", "Install FFmpeg (ffprobe) to validate compressed voice samples, or use PCM WAV.")
+        try:
+            r = subprocess.run([probe, "-v", "error", "-show_entries", "format=duration", "-of", "json", str(path)], capture_output=True, timeout=15, check=True)
+            seconds = float(json.loads(r.stdout)["format"]["duration"])
+        except (ValueError, KeyError, subprocess.SubprocessError):
+            raise VoiceError("VOICE_INVALID", "Unable to validate reference duration.") from None
+    if not 0 < seconds <= 30:
+        raise VoiceError("VOICE_INVALID", "Reference duration must be greater than zero and at most 30 seconds.")
+    return seconds
+
+
+def validate_profile(p):
+    required = {"schema_version", "id", "name", "version", "description", "style", "settings", "reference"}
+    if not isinstance(p, dict) or set(p) != required or p.get("schema_version") != 1:
+        raise VoiceError("VOICE_INVALID", "Unsupported voice profile schema.")
+    if not isinstance(p["id"], str) or not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", p["id"]):
+        raise VoiceError("VOICE_INVALID", "Voice ID must use 1–64 lowercase letters, digits or hyphens.")
+    if p["id"] in {"con", "prn", "aux", "nul", *[f"com{i}" for i in range(1, 10)], *[f"lpt{i}" for i in range(1, 10)]}:
+        raise VoiceError("VOICE_INVALID", "Voice ID is a reserved platform filename.")
+    if type(p["version"]) is not int or p["version"] < 1:
+        raise VoiceError("VOICE_INVALID", "Voice version must be a positive integer.")
+    for field, limit, empty in [("name", 80, False), ("description", 1000, True), ("style", 2000, True)]:
+        value = p[field]
+        if not isinstance(value, str) or len(value) > limit or (not empty and not value.strip()) or any(ord(c) < 32 for c in value):
+            raise VoiceError("VOICE_INVALID", "Invalid voice name, description or style.")
+    if "@" in p["name"]:
+        raise VoiceError("VOICE_INVALID", "Voice name cannot contain @ (reserved for version selection).")
+    settings = p["settings"]
+    if not isinstance(settings, dict) or set(settings) - SETTINGS:
+        raise VoiceError("VOICE_INVALID", "Unsupported voice settings.")
+    payload = {"model": settings.get("model", "seed-audio-1.0"), "text_prompt": "validation", "audio_config": {k: v for k, v in settings.items() if k != "model"}}
+    if validate_payload(payload):
+        raise VoiceError("VOICE_INVALID", "Voice output settings are invalid.")
+    ref = p["reference"]
+    if not isinstance(ref, dict) or set(ref) != {"file", "sha256", "seconds"} or ref["file"] not in {"sample.wav", "sample.mp3", "sample.ogg", "sample.opus"} or not isinstance(ref["sha256"], str) or not re.fullmatch(r"[0-9a-f]{64}", ref["sha256"]) or type(ref["seconds"]) not in {int, float} or not 0 < ref["seconds"] <= 30:
+        raise VoiceError("VOICE_INVALID", "Invalid voice reference metadata.")
+    return p
+
+
+def profiles():
+    root = library()
+    if root.is_symlink():
+        raise VoiceError("VOICE_UNSAFE_FILE", "Voice library cannot be a symlink.")
+    if not root.exists():
+        return []
+    items = []
+    for folder in root.iterdir():
+        if folder.name.startswith("."):
+            continue
+        if folder.is_symlink() or not folder.is_dir():
+            raise VoiceError("VOICE_UNSAFE_FILE", "Invalid library entry.")
+        for revision in folder.iterdir():
+            if revision.is_symlink() or not revision.is_dir() or not revision.name.isdigit():
+                raise VoiceError("VOICE_UNSAFE_FILE", "Invalid voice revision.")
+            f = revision / "profile.json"
+            regular(f)
+            try:
+                p = validate_profile(json.loads(f.read_text(encoding="utf-8")))
+            except (ValueError, TypeError):
+                raise VoiceError("VOICE_INVALID", "Stored voice profile is invalid; preserve it for recovery.") from None
+            if p["id"] != folder.name or str(p["version"]) != revision.name:
+                raise VoiceError("VOICE_INVALID", "Voice path and profile identity differ.")
+            items.append(p)
+    return items
+
+
+def get(selector):
+    identity, sep, revision = selector.rpartition("@")
+    if not sep:
+        identity, revision = selector, None
+    if revision is not None and (not revision.isdigit() or int(revision) < 1):
+        raise VoiceError("VOICE_INVALID", "Use NAME@VERSION or ID@VERSION.")
+    found = [p for p in profiles() if identity in {p["id"], p["name"]} and (revision is None or p["version"] == int(revision))]
+    if not found:
+        raise VoiceError("VOICE_NOT_FOUND", "Voice not found; use voice list to choose an installed voice.")
+    if len({p["id"] for p in found}) != 1:
+        raise VoiceError("VOICE_AMBIGUOUS", "Voice name is ambiguous; select its ID.")
+    p = max(found, key=lambda p: p["version"])
+    sample = library() / p["id"] / str(p["version"]) / p["reference"]["file"]
+    regular(sample)
+    if hashlib.sha256(sample.read_bytes()).hexdigest() != p["reference"]["sha256"]:
+        raise VoiceError("VOICE_INTEGRITY_FAILED", "Voice reference hash differs; recover the original sample.")
+    return p, sample
+
+
+def commit(p, sample_bytes):
+    validate_profile(p)
+    if not 0 < len(sample_bytes) <= MAX_BYTES or hashlib.sha256(sample_bytes).hexdigest() != p["reference"]["sha256"]:
+        raise VoiceError("VOICE_INTEGRITY_FAILED", "Voice sample hash or size is invalid.")
+    root = library()
+    if root.is_symlink():
+        raise VoiceError("VOICE_UNSAFE_FILE", "Voice library cannot be a symlink.")
+    root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    lock = root / ".write-lock"
+    try:
+        fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        raise VoiceError("VOICE_BUSY", "Another library operation holds the lock; inspect it before retrying.") from None
+    stage = root / (".pending-" + str(time.time_ns()))
+    try:
+        existing = profiles()
+        if any(q["id"] != p["id"] and (q["name"] in {p["id"], p["name"]} or q["id"] == p["name"]) for q in existing):
+            raise VoiceError("VOICE_NAME_CONFLICT", "Name or ID already belongs to another voice.")
+        versions = [q["version"] for q in existing if q["id"] == p["id"]]
+        p = {**p, "version": max(versions, default=0) + 1}
+        stage.mkdir(mode=0o700)
+        sample = stage / p["reference"]["file"]
+        with sample.open("xb") as f:
+            f.write(sample_bytes)
+        sample.chmod(0o600)
+        # Validate imported bytes too; duration metadata alone is not trusted.
+        seconds = audio_seconds(sample)
+        if abs(seconds - p["reference"]["seconds"]) > .1:
+            raise VoiceError("VOICE_INVALID", "Reference duration differs from its metadata.")
+        with (stage / "profile.json").open("x", encoding="utf-8") as f:
+            json.dump(p, f, ensure_ascii=False, indent=2)
+        (stage / "profile.json").chmod(0o600)
+        target = root / p["id"] / str(p["version"])
+        target.parent.mkdir(mode=0o700, exist_ok=True)
+        stage.rename(target)
+        return {"ok": True, "voice": p, "library": str(root), "reference_path": str(target / p["reference"]["file"])}
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage)
+        os.close(fd)
+        lock.unlink()
+
+
+def save(args):
+    path = Path(args.audio_file).expanduser().absolute()
+    seconds = audio_seconds(path)
+    data = path.read_bytes()
+    settings = {k: getattr(args, k) for k in SETTINGS if getattr(args, k, None) is not None}
+    profile = {"schema_version": 1, "id": args.id, "name": args.name, "version": 1, "description": args.description,
+               "style": args.style, "settings": settings,
+               "reference": {"file": "sample" + path.suffix.lower(), "sha256": hashlib.sha256(data).hexdigest(), "seconds": seconds}}
+    return commit(profile, data)
+
+
+def export_voice(selector, destination):
+    p, sample = get(selector)
+    output = Path(destination).expanduser().absolute()
+    bundle = {"schema_version": 1, "profile": p, "audio_base64": base64.b64encode(sample.read_bytes()).decode("ascii")}
+    try:
+        with output.open("x", encoding="utf-8") as f:
+            json.dump(bundle, f, ensure_ascii=False)
+    except FileExistsError:
+        raise VoiceError("OUTPUT_EXISTS", "Export destination exists; choose a new filename.") from None
+    output.chmod(0o600)
+    return {"ok": True, "exported_to": str(output), "voice": {"id": p["id"], "name": p["name"], "version": p["version"]}}
+
+
+def import_voice(filename):
+    path = Path(filename).expanduser()
+    regular(path)
+    try:
+        bundle = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(bundle, dict) or set(bundle) != {"schema_version", "profile", "audio_base64"} or bundle["schema_version"] != 1:
+            raise ValueError()
+        p = validate_profile(bundle["profile"])
+        data = base64.b64decode(bundle["audio_base64"], validate=True)
+    except (ValueError, TypeError, KeyError):
+        raise VoiceError("VOICE_INVALID", "Invalid voice bundle.") from None
+    return commit(p, data)
+
+
+def apply(args, narration):
+    p, sample = get(args.voice)
+    if any(getattr(args, flag, None) for flag in ["audio_reference", "audio_file", "image_url", "image_file"]) or args.generate_cmd == "image-ref":
+        raise VoiceError("VOICE_REFERENCE_CONFLICT", "Select either a named voice or explicit audio/image references.")
+    settings = dict(p["settings"])
+    for k in SETTINGS:
+        if getattr(args, k, None) is not None:
+            settings[k] = getattr(args, k)
+    prompt = "@音频1 使用参考音频中同一位讲述者，保持其音色和表达风格。" + p["style"] + "。单人干声，只朗读以下正文。\n\n" + narration
+    payload = build_payload(prompt=prompt, model=settings.get("model"), audio_files=[str(sample)], output_format=settings.get("format"), sample_rate=settings.get("sample_rate"), speech_rate=settings.get("speech_rate"), pitch_rate=settings.get("pitch_rate"), loudness_rate=settings.get("loudness_rate"), enable_subtitle=args.subtitle)
+    args.voice_receipt = {"id": p["id"], "name": p["name"], "version": p["version"], "reference_sha256": p["reference"]["sha256"], "style": p["style"], "effective_settings": {"model": payload["model"], **payload["audio_config"]}}
+    return payload