@petercjl/seedaudiocli 0.1.1 → 0.2.0

package/seedaudiocli/cli.py

@@ -4,12 +4,15 @@ import argparse
 import json
 import os
 import sys
+import time
+import uuid
+import hashlib
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any
 
 from . import __version__
-from . import evolink
+from . import official
 from .config import (
     DEFAULT_BASE_URL,
     DEFAULT_MODEL,
@@ -22,7 +25,7 @@ from .config import (
     import_config,
     ConfigError,
 )
-from .jobs import append_job, append_status, find_by_hash, read_jobs
+from .jobs import root, job_dir, save_record, read_job, write_json, recover_audio, export_audio, find_by_hash, read_jobs, validate_output_name
 from .payloads import build_payload, read_prompt, request_hash, validate_payload
 
 
@@ -31,20 +34,19 @@ def print_json(data: Any) -> None:
 
 
 def add_generation_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--prompt", help="Prompt text, max 1500 characters.")
+    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: doubao-seed-audio-1-0.")
+    parser.add_argument("--model", help="Override model id. Default: seed-audio-1.0.")
     parser.add_argument("--format", choices=["wav", "mp3", "pcm", "ogg_opus"], help="Output audio format.")
-    parser.add_argument("--sample-rate", type=int, choices=[8000, 16000, 24000, 32000, 44100, 48000])
-    parser.add_argument("--speech-rate", type=float, help="Speech-rate multiplier from 0.5 to 2.0.")
-    parser.add_argument("--loudness-rate", type=float, help="Loudness multiplier from 0.5 to 2.0.")
+    parser.add_argument("--sample-rate", type=int, choices=[8000, 16000, 24000, 32000, 40000, 44100, 48000])
+    parser.add_argument("--speech-rate", type=int, help="Speech-rate adjustment from -50 to 100; 0 is unchanged.")
+    parser.add_argument("--loudness-rate", type=int, help="Loudness adjustment from -50 to 100; 0 is unchanged.")
     parser.add_argument("--pitch-rate", type=int, help="Pitch adjustment in semitones from -12 to 12.")
-    parser.add_argument("--callback-url", help="HTTPS callback URL for task completion.")
+    parser.add_argument("--subtitle", action="store_true", help="Return timestamped subtitles when supported.")
     parser.add_argument("--dry-run", action="store_true", help="Print payload without creating a task.")
     parser.add_argument("--force", action="store_true", help="Create a new task even if the same request hash exists.")
-    parser.add_argument("--wait", action="store_true", help="Wait until the task reaches a terminal state.")
-    parser.add_argument("--interval", type=int, default=5, help="Polling interval in seconds for --wait.")
-    parser.add_argument("--timeout", type=int, default=1800, help="Polling timeout in seconds for --wait.")
+    parser.add_argument("--wait", action="store_true", help="Compatibility flag: official generation always waits for its response.")
+    parser.add_argument("--timeout", type=int, default=300, help="HTTP request timeout in seconds; a timeout never resubmits.")
     parser.add_argument("--download", help="Download completed audio to this directory. Implies --wait.")
     parser.add_argument("--output-name", help="Filename stem for downloaded audio. Defaults to task id.")
 
@@ -63,70 +65,69 @@ def generation_payload_from_args(args: argparse.Namespace) -> dict[str, Any]:
         speech_rate=args.speech_rate,
         loudness_rate=args.loudness_rate,
         pitch_rate=args.pitch_rate,
-        callback_url=args.callback_url,
+        enable_subtitle=args.subtitle,
+        audio_files=list(getattr(args, "audio_file", None) or []),
+        image_files=list(getattr(args, "image_file", None) or []),
     )
 
 
-def download_from_response(response: dict[str, Any], out_dir: Path, output_name: str | None = None) -> list[str]:
-    urls = evolink.extract_audio_urls(response)
-    if not urls:
-        return []
-    formats: list[str | None] = []
-    for item in response.get("result_data") or []:
-        if isinstance(item, dict):
-            formats.append(item.get("format"))
-    out_dir.mkdir(parents=True, exist_ok=True)
-    task_id = str(response.get("id") or "audio")
-    downloaded: list[str] = []
-    for idx, url in enumerate(urls, 1):
-        result_format = formats[idx - 1] if idx - 1 < len(formats) else None
-        ext = {"ogg_opus": "ogg", "pcm": "pcm"}.get(str(result_format), str(result_format or "")) or evolink.infer_extension(url)
-        stem = output_name or task_id
-        suffix = "" if len(urls) == 1 else f"_{idx}"
-        out_path = out_dir / f"{stem}{suffix}.{ext}"
-        evolink.download_url(url, out_path)
-        downloaded.append(str(out_path))
-    return downloaded
-
-
-def submit_or_print(payload: dict[str, Any], args: argparse.Namespace) -> int:
+def submit_or_print(payload, args):
     errors = validate_payload(payload)
     h = request_hash(payload)
     if errors:
-        result: dict[str, Any] = {"ok": False, "errors": errors}
-        if args.dry_run:
-            result["payload"] = payload
-            result["request_hash"] = h
-        print_json(result)
+        print_json({"ok": False, "code": "PAYLOAD_INVALID", "errors": errors})
         return 2
+    if args.timeout <= 0:
+        raise ValueError("timeout must be positive.")
+    validate_output_name(args.output_name)
+    if args.download and Path(args.download).expanduser().exists() and not Path(args.download).expanduser().is_dir():
+        raise ValueError("download destination must be a directory.")
     if args.dry_run:
-        print_json({"ok": True, "dry_run": True, "request_hash": h, "payload": payload})
-        return 0
-
-    existing = find_by_hash(h)
-    if existing and not args.force:
-        print_json({"ok": True, "deduped": True, "request_hash": h, "job": existing})
+        print_json({"ok": True, "dry_run": True, "request_hash": h, "payload": payload,
+                    "provider": "Volcengine", "endpoint": DEFAULT_BASE_URL + "/api/v3/tts/create"})
         return 0
-
-    response = evolink.create_task(payload)
-    task_id = evolink.extract_task_id(response)
-    append_job({"event": "create", "request_hash": h, "task_id": task_id, "payload": payload, "response": response})
-
-    result: dict[str, Any] = {"ok": True, "request_hash": h, "task_id": task_id, "response": response}
-    should_wait = args.wait or bool(args.download)
-    if should_wait and task_id:
-        final = evolink.wait_for_task(task_id, interval=args.interval, timeout=args.timeout)
-        status = evolink.extract_status(final)
-        append_status(task_id, status, final)
-        result["final_status"] = status
-        result["final_response"] = final
+    seedaudio_base_url()
+    key = seedaudio_api_key()
+    # Account-scoped deduplication avoids reusing another credential's result.
+    h = hashlib.sha256((h + (key or "")).encode()).hexdigest()
+    lock = root() / (h + ".lock")
+    try:
+        fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        raise official.SeedAudioError("An identical request is in progress or was interrupted. Inspect task jobs before clearing its local lock.", "REQUEST_BUSY") from None
+    os.close(fd)
+    try:
+        existing = find_by_hash(h)
+        if existing and not args.force and existing["status"] != "failed":
+            record = recover_audio(existing)
+            if record["status"] != "completed":
+                raise official.SeedAudioError("Previous generation outcome is unknown. Inspect the local record; a new paid attempt requires explicit authorization and --force.", "SUBMISSION_UNKNOWN", details={"task_id": record["task_id"]})
+            result = {"ok": True, "deduped": True, "task_id": record["task_id"], "job": record}
+        else:
+            task_id = str(uuid.uuid4())
+            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")}
+            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)
+            try:
+                response = official.create_audio(payload, task_id, args.timeout)
+                write_json(job_dir(task_id) / "response.json", response)
+                record = recover_audio(record)
+            except official.SeedAudioError as e:
+                record.update(status="unknown" if e.code in {"SUBMISSION_UNKNOWN", "OUTPUT_CONTRACT_FAILED"} else "failed",
+                              error_code=e.code, details=e.details)
+                save_record(record)
+                e.details.setdefault("task_id", task_id)
+                raise
+            result = {"ok": True, "task_id": task_id, "job": record}
         if args.download:
-            downloaded = download_from_response(final, Path(args.download).expanduser(), args.output_name)
-            result["downloaded_to"] = downloaded
-    print_json(result)
-    if result.get("final_status") and result["final_status"] != "completed":
-        return 2
-    return 0
+            result["downloaded_to"] = export_audio(record, args.download, args.output_name)
+        print_json(result)
+        return 0
+    finally:
+        lock.unlink()
 
 
 def cmd_config(args: argparse.Namespace) -> int:
@@ -139,7 +140,6 @@ def cmd_config(args: argparse.Namespace) -> int:
     if args.config_cmd == "init":
         path = write_default_env(
             import_current_env=args.import_env,
-            import_key_file=args.import_key_file,
             overwrite=args.overwrite,
         )
         print(f"Wrote config: {path}")
@@ -193,45 +193,37 @@ def cmd_models(_: argparse.Namespace) -> int:
             "default": DEFAULT_MODEL,
             "configured": seedaudio_model(),
             "base_url_default": DEFAULT_BASE_URL,
-            "notes": "EvoLink currently exposes doubao-seed-audio-1-0 for this CLI.",
+            "notes": "Official Doubao Speech Seed Audio; synchronous HTTP response with local result recovery.",
         }
     )
     return 0
 
 
 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 == "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_task(args: argparse.Namespace) -> int:
-    if args.task_cmd == "get":
-        response = evolink.get_task(args.task_id)
-        append_status(args.task_id, evolink.extract_status(response), response)
-        print_json(response)
-        return 0
-    if args.task_cmd == "wait":
-        response = evolink.wait_for_task(args.task_id, interval=args.interval, timeout=args.timeout)
-        status = evolink.extract_status(response)
-        append_status(args.task_id, status, response)
-        result: dict[str, Any] = {"task_id": args.task_id, "status": status, "response": response}
-        if args.download:
-            result["downloaded_to"] = download_from_response(response, Path(args.download).expanduser(), args.output_name)
-        print_json(result)
-        return 0 if status == "completed" else 2
-    if args.task_cmd == "url":
-        response = evolink.get_task(args.task_id)
-        status = evolink.extract_status(response)
-        append_status(args.task_id, status, response)
-        result: dict[str, Any] = {"task_id": args.task_id, "status": status, "urls": evolink.extract_audio_urls(response)}
-        if args.include_response:
-            result["response"] = response
-        print_json(result)
-        return 0 if result["urls"] else 2
+def cmd_task(args):
     if args.task_cmd == "jobs":
-        print_json({"job_store": str(job_store_path()), "jobs": read_jobs()[-args.limit :]})
+        if args.limit < 1:
+            raise ValueError("limit must be positive.")
+        print_json({"ok": True, "job_store": str(root()), "jobs": read_jobs()[-args.limit:]})
         return 0
-    raise SystemExit("unknown task command")
+    record = recover_audio(read_job(args.task_id))
+    result = {"ok": record["status"] == "completed", "task_id": args.task_id, "job": record,
+              "remote_polling": False}
+    if args.task_cmd in {"download", "wait"} and args.download:
+        result["downloaded_to"] = export_audio(record, args.download, args.output_name)
+    if args.task_cmd == "url":
+        result["urls"] = [record["url"]] if record.get("url") else []
+        result["note"] = "Provider URL may expire; cached local audio remains available."
+    print_json(result)
+    return 0 if result["ok"] else 2
 
 
 def cmd_payload(args: argparse.Namespace) -> int:
@@ -248,7 +240,6 @@ def cmd_payload(args: argparse.Namespace) -> int:
             dry_run=False,
             force=args.force,
             wait=args.wait,
-            interval=args.interval,
             timeout=args.timeout,
             download=args.download,
             output_name=args.output_name,
@@ -258,7 +249,7 @@ def cmd_payload(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="seedaudiocli", description="System CLI for EvoLink Doubao Seed-Audio 1.0 generation.")
+    parser = argparse.ArgumentParser(prog="seedaudiocli", description="Official Volcengine Seed Audio generation and local result recovery.")
     parser.add_argument("--version", action="version", version=f"seedaudiocli {__version__}")
     sub = parser.add_subparsers(dest="cmd", required=True)
 
@@ -275,7 +266,6 @@ def build_parser() -> argparse.ArgumentParser:
     config_import.add_argument("--replace", action="store_true", help="Back up existing configuration before replacement.")
     config_init = config_sub.add_parser("init", help="Create env config file.")
     config_init.add_argument("--import-env", action="store_true", help="Copy current SEEDAUDIO_* values into the env file.")
-    config_init.add_argument("--import-key-file", help="Import Seed-Audio EvoLink key block from a local note file.")
     config_init.add_argument("--overwrite", action="store_true", help="Overwrite existing env file.")
     config.set_defaults(func=cmd_config)
 
@@ -299,28 +289,34 @@ def build_parser() -> argparse.ArgumentParser:
 
     gen_audio = gen_sub.add_parser("audio-ref", help="Reference-audio or preset-voice generation.")
     add_generation_args(gen_audio)
-    gen_audio.add_argument("--audio-reference", action="append", required=True, help="Preset voice_type or reference-audio URL. Repeat up to 3 times.")
+    gen_audio.add_argument("--audio-reference", action="append", help="Preset speaker ID or audio URL; reference order precedes audio-file entries.")
+    gen_audio.add_argument("--audio-file", action="append", help="Local reference recording up to 10 MiB and 30 seconds; repeat up to 3 total references.")
     gen_audio.set_defaults(func=cmd_generate)
 
     gen_image = gen_sub.add_parser("image-ref", help="Reference-image-guided audio generation.")
     add_generation_args(gen_image)
-    gen_image.add_argument("--image-url", action="append", required=True, help="Public jpeg/png/webp image URL. Exactly one is supported by the API.")
+    gen_image.add_argument("--image-url", action="append", help="Public jpeg/png/webp URL; exactly one image reference.")
+    gen_image.add_argument("--image-file", action="append", help="Local jpeg/png/webp image up to 10 MiB.")
     gen_image.set_defaults(func=cmd_generate)
 
-    task = sub.add_parser("task", help="Task status, wait, URLs, and history.")
+    task = sub.add_parser("task", help="Local official generation records and cached audio; no remote polling.")
     task_sub = task.add_subparsers(dest="task_cmd", required=True)
-    task_get = task_sub.add_parser("get", help="Fetch raw task JSON.")
+    task_get = task_sub.add_parser("get", help="Read a local generation record.")
     task_get.add_argument("task_id")
     task_get.set_defaults(func=cmd_task)
 
-    task_wait = task_sub.add_parser("wait", help="Wait for task completion.")
+    task_wait = task_sub.add_parser("wait", help="Recover a saved response locally (compatibility alias).")
     task_wait.add_argument("task_id")
-    task_wait.add_argument("--interval", type=int, default=5)
-    task_wait.add_argument("--timeout", type=int, default=1800)
     task_wait.add_argument("--download", help="Download completed audio to this directory.")
     task_wait.add_argument("--output-name", help="Filename stem for downloaded audio.")
     task_wait.set_defaults(func=cmd_task)
 
+    task_download = task_sub.add_parser("download", help="Export cached audio without a new generation.")
+    task_download.add_argument("task_id")
+    task_download.add_argument("--download", required=True)
+    task_download.add_argument("--output-name")
+    task_download.set_defaults(func=cmd_task)
+
     task_url = task_sub.add_parser("url", help="Print completed audio URLs.")
     task_url.add_argument("task_id")
     task_url.add_argument("--include-response", action="store_true")
@@ -342,8 +338,7 @@ def build_parser() -> argparse.ArgumentParser:
     payload_submit.add_argument("file")
     payload_submit.add_argument("--force", action="store_true")
     payload_submit.add_argument("--wait", action="store_true")
-    payload_submit.add_argument("--interval", type=int, default=5)
-    payload_submit.add_argument("--timeout", type=int, default=1800)
+    payload_submit.add_argument("--timeout", type=int, default=300)
     payload_submit.add_argument("--download")
     payload_submit.add_argument("--output-name")
     payload_submit.set_defaults(func=cmd_payload)
@@ -356,7 +351,6 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     try:
         network = ((args.cmd == "generate" and not args.dry_run)
-                   or (args.cmd == "task" and args.task_cmd != "jobs")
                    or (args.cmd == "payload" and args.payload_cmd == "submit"))
         if network and not seedaudio_api_key():
             if sys.stdin.isatty():
@@ -367,7 +361,7 @@ def main(argv: list[str] | None = None) -> int:
     except ConfigError as e:
         print_json({"ok": False, "code": e.code, "error": str(e)})
         return 2
-    except (ValueError, evolink.SeedAudioError) as e:
+    except (ValueError, official.SeedAudioError) as e:
         message = str(e)
         try:
             key = seedaudio_api_key()
@@ -375,7 +369,7 @@ def main(argv: list[str] | None = None) -> int:
                 message = message.replace(key, "[REDACTED]")
         except ConfigError:
             pass
-        print_json({"ok": False, "code": getattr(e, "code", "REQUEST_FAILED"), "error": message})
+        print_json({"ok": False, "code": getattr(e, "code", "REQUEST_FAILED"), "error": message, "details": getattr(e, "details", {})})
         return 1
     except (OSError, EOFError, KeyboardInterrupt):
         print_json({"ok": False, "code": "LOCAL_OPERATION_FAILED", "error": "Local operation failed or was cancelled."})

package/seedaudiocli/config.py

@@ -10,8 +10,8 @@ from urllib.parse import urlparse
 
 
 APP_NAME = "seedaudiocli"
-DEFAULT_BASE_URL = "https://api.evolink.ai"
-DEFAULT_MODEL = "doubao-seed-audio-1-0"
+DEFAULT_BASE_URL = "https://openspeech.bytedance.com"
+DEFAULT_MODEL = "seed-audio-1.0"
 DEFAULT_FORMAT = "mp3"
 DEFAULT_SAMPLE_RATE = "44100"
 
@@ -69,12 +69,14 @@ def validate_config(values: dict[str, str], require_key: bool = True) -> dict[st
         valid_url = False
     if not valid_url:
         raise ConfigError("CONFIG_INVALID", "API base URL must be HTTPS without credentials, query or fragment.")
+    if base.rstrip("/") != DEFAULT_BASE_URL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Import an official Doubao Speech configuration; this version only connects to openspeech.bytedance.com.")
     if values.get("SEEDAUDIO_DEFAULT_FORMAT", DEFAULT_FORMAT) not in {"mp3", "wav", "pcm", "ogg_opus"}:
         raise ConfigError("CONFIG_INVALID", "Unsupported audio format.")
-    if values.get("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE) not in {"8000", "16000", "24000", "32000", "44100", "48000"}:
+    if values.get("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE) not in {"8000", "16000", "24000", "32000", "40000", "44100", "48000"}:
         raise ConfigError("CONFIG_INVALID", "Unsupported sample rate.")
-    if not values.get("SEEDAUDIO_MODEL", DEFAULT_MODEL).strip():
-        raise ConfigError("CONFIG_INVALID", "Model must not be empty.")
+    if values.get("SEEDAUDIO_MODEL", DEFAULT_MODEL) != DEFAULT_MODEL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Import an official configuration using model seed-audio-1.0.")
     return {**values, "SEEDAUDIO_API_KEY": key}
 
 
@@ -184,18 +186,17 @@ def seedaudio_api_key() -> str | None:
 
 
 def seedaudio_base_url() -> str:
-    raw = get_setting("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL) or DEFAULT_BASE_URL
-    raw = raw.rstrip("/")
-    suffix = "/v1/audios/generations"
-    if raw.endswith(suffix):
-        raw = raw[: -len(suffix)]
-    if raw.endswith("/v1"):
-        raw = raw[: -len("/v1")]
-    return raw.rstrip("/")
+    raw = (get_setting("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+    if raw != DEFAULT_BASE_URL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Only the official Doubao Speech endpoint is supported; import the official configuration.")
+    return raw
 
 
 def seedaudio_model() -> str:
-    return get_setting("SEEDAUDIO_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+    model = get_setting("SEEDAUDIO_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+    if model != DEFAULT_MODEL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "The configured model must be seed-audio-1.0.")
+    return model
 
 
 def default_format() -> str:
@@ -207,33 +208,8 @@ def default_sample_rate() -> int:
     return int(value)
 
 
-def parse_evolink_seed_audio_file(path: Path) -> tuple[str | None, str | None]:
-    if not path.exists():
-        return None, None
-    text = path.read_text(errors="ignore")
-    in_seed = False
-    api_key: str | None = None
-    base_url: str | None = None
-    for raw in text.splitlines():
-        line = raw.strip()
-        low = line.lower()
-        if "seed-audio" in low and "evolink" in low:
-            in_seed = True
-            continue
-        if not in_seed:
-            continue
-        norm = line.replace("：", ":")
-        if norm.lower().startswith("base url") and ":" in norm:
-            base_url = norm.split(":", 1)[1].strip()
-        elif norm.lower().startswith("api key") and ":" in norm:
-            api_key = norm.split(":", 1)[1].strip()
-            break
-    return api_key, base_url
-
-
 def write_default_env(
     import_current_env: bool = False,
-    import_key_file: str | None = None,
     overwrite: bool = False,
 ) -> Path:
     path = config_path()
@@ -251,11 +227,6 @@ def write_default_env(
         else DEFAULT_SAMPLE_RATE
     )
 
-    if import_key_file:
-        key, base = parse_evolink_seed_audio_file(Path(import_key_file).expanduser())
-        current_key = key or current_key
-        current_base = base or current_base
-
     save_config({"SEEDAUDIO_API_KEY": current_key, "SEEDAUDIO_BASE_URL": current_base,
                  "SEEDAUDIO_MODEL": current_model, "SEEDAUDIO_DEFAULT_FORMAT": current_format,
                  "SEEDAUDIO_DEFAULT_SAMPLE_RATE": current_sample_rate}, replace=overwrite, require_key=False)

package/seedaudiocli/jobs.py

@@ -1,46 +1,134 @@
 from __future__ import annotations
 
+import base64
 import json
+import os
+import re
+import shutil
+import tempfile
 import time
 from pathlib import Path
-from typing import Any
 
-from .config import job_store_path
+from .config import state_dir
+from .official import SeedAudioError
 
 
-TERMINAL_STATES = {"completed", "failed", "cancelled", "canceled", "expired"}
+def root():
+    p = state_dir() / "official"
+    p.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return p
 
 
-def append_job(record: dict[str, Any], path: Path | None = None) -> None:
-    path = path or job_store_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    record = {"created_at": int(time.time()), **record}
-    with path.open("a", encoding="utf-8") as f:
-        f.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+def job_dir(task_id):
+    if not re.fullmatch(r"[a-f0-9-]{36}", task_id):
+        raise SeedAudioError("Expected a local official generation record ID.", "TASK_NOT_FOUND")
+    return root() / task_id
 
 
-def read_jobs(path: Path | None = None) -> list[dict[str, Any]]:
-    paths = [path or job_store_path()]
-    jobs: list[dict[str, Any]] = []
-    for read_path in paths:
-        if not read_path.exists():
+def write_json(path, value):
+    fd, tmp = tempfile.mkstemp(prefix=".record-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(value, f, ensure_ascii=False)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+        os.chmod(path, 0o600)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def save_record(record):
+    write_json(job_dir(record["task_id"]) / "record.json", record)
+
+
+def read_job(task_id):
+    p = job_dir(task_id) / "record.json"
+    if not p.is_file():
+        raise SeedAudioError("Local official generation record not found.", "TASK_NOT_FOUND")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def read_jobs():
+    jobs = []
+    for p in root().glob("*/record.json"):
+        try:
+            jobs.append(json.loads(p.read_text(encoding="utf-8")))
+        except (ValueError, OSError):
             continue
-        for line in read_path.read_text(encoding="utf-8").splitlines():
-            if not line.strip():
-                continue
-            try:
-                jobs.append(json.loads(line))
-            except json.JSONDecodeError:
-                continue
-    return jobs
-
-
-def find_by_hash(request_hash: str) -> dict[str, Any] | None:
-    for job in reversed(read_jobs()):
-        if job.get("request_hash") == request_hash and job.get("task_id"):
-            return job
+    return sorted(jobs, key=lambda x: x.get("created_at", 0))
+
+
+def find_by_hash(h):
+    for record in reversed(read_jobs()):
+        if record.get("request_hash") == h:
+            return record
     return None
 
 
-def append_status(task_id: str, status: str, response: dict[str, Any] | None = None) -> None:
-    append_job({"event": "status", "task_id": task_id, "status": status, "response": response or {}})
+def recover_audio(record):
+    d = job_dir(record["task_id"])
+    response_path = d / "response.json"
+    if not response_path.is_file():
+        return record
+    # Raw response is saved before decoding/export, so local failures are recoverable.
+    response = json.loads(response_path.read_text(encoding="utf-8"))
+    try:
+        audio = base64.b64decode(response.get("audio", ""), validate=True)
+        if not audio:
+            raise ValueError()
+    except (ValueError, TypeError):
+        raise SeedAudioError("No valid audio bytes in the saved response; do not resubmit automatically.", "OUTPUT_CONTRACT_FAILED") from None
+    fmt = record["format"]
+    p = d / ("audio." + ("ogg" if fmt == "ogg_opus" else fmt))
+    if p.exists():
+        if p.read_bytes() != audio:
+            raise SeedAudioError("Cached audio differs from the saved response.", "OUTPUT_EXISTS")
+    else:
+        fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(audio)
+    record.update(status="completed", audio_path=str(p), bytes=len(audio),
+                  duration=response.get("duration"), original_duration=response.get("original_duration"),
+                  logid=response.get("logid"), url=response.get("url"))
+    if response.get("subtitle") is not None:
+        sp = d / "subtitle.json"
+        if not sp.exists():
+            write_json(sp, response["subtitle"])
+        record["subtitle_path"] = str(sp)
+    save_record(record)
+    return record
+
+
+def validate_output_name(stem):
+    if stem and (stem in {".", ".."} or any(c in stem for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in stem)):
+        raise ValueError("output-name must be a filename stem without path separators.")
+
+
+def export_audio(record, destination, output_name=None):
+    record = recover_audio(record)
+    if record.get("status") != "completed":
+        raise SeedAudioError("No saved successful response. Official API has no remote task-query operation.", "SUBMISSION_UNKNOWN")
+    stem = output_name or record["task_id"]
+    if stem in {".", ".."} or any(c in stem for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in stem):
+        raise ValueError("output-name must be a filename stem without path separators.")
+    out = Path(destination).expanduser().resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for field, suffix in [("audio_path", Path(record["audio_path"]).suffix), ("subtitle_path", ".subtitle.json")]:
+        if field not in record:
+            continue
+        src = Path(record[field])
+        target = out / (stem + suffix)
+        if target.is_symlink():
+            raise SeedAudioError("Output target is a symlink.", "OUTPUT_EXISTS")
+        if target.exists():
+            if not target.is_file() or target.read_bytes() != src.read_bytes():
+                raise SeedAudioError("Output already exists; choose another output-name.", "OUTPUT_EXISTS")
+        else:
+            fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, "wb") as f, src.open("rb") as source:
+                shutil.copyfileobj(source, f)
+        paths.append(str(target))
+    return paths