nnnotes 0.1.0__py3-none-any.whl

nnnotes/live2d.py

@@ -0,0 +1,235 @@
+"""Live2D (Cubism) model: Cubism-for-Unity prefab -> prefab.json + Cubism runtime files.
+
+Components are identified by their MonoScript class (resolved through the APK's
+shared_monoscripts bundle, so the Catalog must be opened with `apk=`).
+
+`extract_runtime` writes what a re-implementation of the game's own runtime needs (`export_runtime` writes the
+same and also returns the exporter state, for callers that export more of the model's bundles):
+
+  <name>.moc3                 CubismMoc._bytes
+  textures/*.png              atlas pages (Texture2D)
+  <name>.prefab.json          the whole model prefab exported by export.Exporter:
+                              every GameObject with every component (CubismRenderer/
+                              MeshRenderer + materials per drawable, controllers,
+                              Live2DCharacter, eye blink, harmonic motion, motion
+                              sync, anchors ...), with the fade motion list, the
+                              expression list and every AnimationClip (Mecanim clip
+                              data + resolved bindings) inlined; plus `canvas` (moc3)
+
+`extract_model` adds the Cubism SDK interchange files for other tools:
+
+  <exp>.exp3.json             CubismExpressionData
+  <name>.physics3.json        CubismPhysicsController._rig (inverse of ToRig), when the
+                              model has physics
+  motions/<m>.motion3.json    CubismFadeMotionData (see motion.py)
+  <name>.model3.json          file refs + EyeBlink/LipSync groups from the
+                              model's own CubismEyeBlinkParameter/CubismMouthParameter
+
+model3.json lists the atlas pages sorted by name (the Cubism Editor's
+texture_NN naming). The texture each drawable is actually drawn with is its
+CubismRenderer._mainTexture in prefab.json, keyed by CubismDrawable._unmanagedIndex
+(the Cubism Core drawable index).
+"""
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+from .catalog import Catalog
+from .config import apk_missing
+from .export import Exporter
+from .jsonio import write_json
+from . import motion as motion_mod
+from .unity import SceneGraph, script_class
+
+# Live2D.Cubism.Core.CubismParameterBlendMode -> exp3.json "Blend"
+EXP_BLEND = {0: "Overwrite", 1: "Add", 2: "Multiply"}
+# Live2D.Cubism.Framework.Physics.CubismPhysicsSourceComponent -> physics3 "Type"
+PHYS_TYPE = {0: "X", 1: "Y", 2: "Angle"}
+# the moc is written as <name>.moc3; prefab.json names it only
+STUB_ASSETS = ("CubismMoc",)
+
+
+def moc3_canvas(moc: bytes) -> dict:
+    """CanvasInfo from a moc3 (section table at 0x40; entry 1 = canvas info)."""
+    if moc[:4] != b"MOC3":
+        raise ValueError("not a moc3")
+    canvas_off = struct.unpack_from("<I", moc, 0x40 + 4)[0]
+    ppu, ox, oy, w, h = struct.unpack_from("<5f", moc, canvas_off)
+    return {"pixelsPerUnit": ppu, "originX": ox, "originY": oy,
+            "width": w, "height": h, "mocVersion": moc[4]}
+
+
+def _vec2(v):
+    return {"X": v["x"], "Y": v["y"]}
+
+
+def physics_json(rig: dict, names: list[str]) -> dict:
+    settings, dictionary = [], []
+    n_in = n_out = n_vtx = 0
+    for i, sr in enumerate(rig["SubRigs"]):
+        sid = f"PhysicsSetting{i + 1}"
+        dictionary.append({"Id": sid, "Name": sr["Name"]})
+        inputs = [{
+            "Source": {"Target": "Parameter", "Id": x["SourceId"]},
+            "Weight": x["Weight"], "Type": PHYS_TYPE[x["SourceComponent"]],
+            "Reflect": bool(x["IsInverted"]),
+        } for x in sr["Input"]]
+        outputs = [{
+            "Destination": {"Target": "Parameter", "Id": x["DestinationId"]},
+            "VertexIndex": x["ParticleIndex"], "Scale": x["AngleScale"],
+            "Weight": x["Weight"], "Type": PHYS_TYPE[x["SourceComponent"]],
+            "Reflect": bool(x["IsInverted"]),
+        } for x in sr["Output"]]
+        verts = [{
+            "Position": _vec2(p["InitialPosition"]), "Mobility": p["Mobility"],
+            "Delay": p["Delay"], "Acceleration": p["Acceleration"], "Radius": p["Radius"],
+        } for p in sr["Particles"]]
+        nz = sr["Normalization"]
+        settings.append({
+            "Id": sid, "Input": inputs, "Output": outputs, "Vertices": verts,
+            "Normalization": {
+                "Position": {k: nz["Position"][k] for k in ("Minimum", "Default", "Maximum")},
+                "Angle": {k: nz["Angle"][k] for k in ("Minimum", "Default", "Maximum")},
+            },
+        })
+        n_in += len(inputs); n_out += len(outputs); n_vtx += len(verts)
+    meta = {
+        "PhysicsSettingCount": len(settings), "TotalInputCount": n_in,
+        "TotalOutputCount": n_out, "VertexCount": n_vtx,
+        "EffectiveForces": {"Gravity": _vec2(rig["Gravity"]), "Wind": _vec2(rig["Wind"])},
+        "PhysicsDictionary": dictionary,
+    }
+    if rig["Fps"] > 0:                       # 0 = unset in physics3 terms
+        meta["Fps"] = rig["Fps"]
+    return {"Version": 3, "Meta": meta, "PhysicsSettings": settings}
+
+
+def expression_json(tt: dict) -> dict:
+    return {
+        "Type": tt["Type"],
+        "FadeInTime": tt["FadeInTime"],
+        "FadeOutTime": tt["FadeOutTime"],
+        "Parameters": [{"Id": p["Id"], "Value": p["Value"], "Blend": EXP_BLEND[p["Blend"]]}
+                       for p in tt["Parameters"]],
+    }
+
+
+def _classes(env) -> dict[str, list]:
+    by_cls: dict[str, list] = {}
+    for o in env.objects:
+        if o.type.name == "MonoBehaviour":
+            by_cls.setdefault(script_class(o), []).append(o)
+    return by_cls
+
+
+def _only(by_cls, cls: str, name: str) -> dict:
+    objs = by_cls.get(cls, [])
+    if len(objs) != 1:
+        raise RuntimeError(f"{name}: {len(objs)} {cls}")
+    return objs[0].read_typetree()
+
+
+@dataclass
+class RuntimeExport:
+    """What `export_runtime` wrote and read: `summary` (the result of `extract_runtime`), the Exporter it wrote with
+    (its shaders, textures, ...), the loaded bundle environment, its scene graph and the MonoBehaviours by script
+    class."""
+    summary: dict
+    exporter: Exporter
+    env: object
+    graph: SceneGraph
+    classes: dict[str, list]
+
+
+def export_runtime(cat: Catalog, key: str, out_dir: Path) -> RuntimeExport:
+    """Write the runtime files of the model `key` into `out_dir` (module docstring) and return them with the
+    exporter state."""
+    if cat.apk is None:
+        raise apk_missing("resolving the Cubism component classes")
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    name = key.rsplit("/", 1)[-1]
+    ex = Exporter(cat, out_dir, inline_meshes=False, stub_assets=STUB_ASSETS)
+    env, graph = ex.load(key)
+    by_cls = _classes(env)
+    moc = bytes(_only(by_cls, "CubismMoc", name)["_bytes"])
+    (out_dir / f"{name}.moc3").write_bytes(moc)
+    prefab = ex.prefab(key, loaded=(env, graph))
+    prefab["canvas"] = moc3_canvas(moc)
+    write_json(out_dir / f"{name}.prefab.json", prefab, indent=None)
+    pages = sorted((o for o in env.objects if o.type.name == "Texture2D"), key=lambda o: o.read().m_Name)
+    tex_files = [ex.texture(o)["texture"] for o in pages]
+    res = {"name": name, "moc3": f"{name}.moc3", "prefab": f"{name}.prefab.json",
+           "moc3Bytes": len(moc), "textures": tex_files, "nodes": len(prefab["nodes"])}
+    return RuntimeExport(res, ex, env, graph, by_cls)
+
+
+def extract_runtime(cat: Catalog, key: str, out_dir: Path) -> dict:
+    """Write the runtime files of the model `key` into `out_dir`; returns the summary: name, moc3, prefab,
+    moc3Bytes, textures, nodes."""
+    return export_runtime(cat, key, out_dir).summary
+
+
+def extract_model(cat: Catalog, key: str, out_dir: Path) -> dict:
+    out_dir = Path(out_dir)
+    rt = export_runtime(cat, key, out_dir)
+    res, env, graph, by_cls = rt.summary, rt.env, rt.graph, rt.classes
+    name = res["name"]
+    (out_dir / "motions").mkdir(parents=True, exist_ok=True)
+
+    def owner_names(cls):
+        return sorted(graph.go[o.read_typetree()["m_GameObject"]["m_PathID"]]["m_Name"]
+                      for o in by_cls.get(cls, []))
+
+    # expressions
+    exp_refs = []
+    for o in by_cls.get("CubismExpressionData", []):
+        tt = o.read_typetree()
+        ename = tt["m_Name"].removesuffix(".exp3")
+        fn = f"{ename}.exp3.json"
+        write_json(out_dir / fn, expression_json(tt), indent=None)
+        exp_refs.append({"Name": ename, "File": fn})
+    exp_refs.sort(key=lambda e: e["Name"])
+
+    # physics (none without a CubismPhysicsController)
+    rig = (_only(by_cls, "CubismPhysicsController", name)["_rig"] if by_cls.get("CubismPhysicsController")
+           else {"SubRigs": []})
+    phys_file = None
+    if rig["SubRigs"]:
+        phys_file = f"{name}.physics3.json"
+        write_json(out_dir / phys_file, physics_json(rig, []), indent=None)
+
+    # motions
+    motions = motion_mod.extract_motions(env, out_dir / "motions")
+    model_fades = json.loads((out_dir / "motions" / "_fades.json").read_text(encoding="utf-8"))
+
+    # model3.json
+    fr = {"Moc": res["moc3"], "Textures": res["textures"]}
+    if phys_file:
+        fr["Physics"] = phys_file
+    if exp_refs:
+        fr["Expressions"] = exp_refs
+
+    def motion_entry(m, f):
+        e = {"File": f"motions/{f}"}
+        for k in ("FadeInTime", "FadeOutTime"):
+            if model_fades[m][k] >= 0:
+                e[k] = model_fades[m][k]
+        return [e]
+    fr["Motions"] = {m: motion_entry(m, f) for m, f in sorted(motions.items())}
+    groups = []
+    eye_ids = owner_names("CubismEyeBlinkParameter")
+    mouth_ids = owner_names("CubismMouthParameter")
+    if eye_ids:
+        groups.append({"Target": "Parameter", "Name": "EyeBlink", "Ids": eye_ids})
+    if mouth_ids:
+        groups.append({"Target": "Parameter", "Name": "LipSync", "Ids": mouth_ids})
+    model3 = {"Version": 3, "FileReferences": fr, "Groups": groups}
+    write_json(out_dir / f"{name}.model3.json", model3)
+
+    return {**res, "model3": f"{name}.model3.json", "expressions": len(exp_refs),
+            "motions": len(motions), "physicsSettings": len(rig["SubRigs"]),
+            "eyeBlink": eye_ids, "lipSync": mouth_ids}

nnnotes/liveaudio.py

@@ -0,0 +1,331 @@
+"""Live sounds for one music: SE / cheer / voice cue sheets, their CRI cue data and the live-audio index.
+
+`extract(cat, master, player, music_id, out_dir)` decodes every cue sheet the live plays in the preview slice
+(auto play at Perfect, fresh profile, default options) with `cri.decode` into `<out>/audio/<cueSheet>/`
+and writes `<out>/audio/live-audio.json`:
+
+  sounds        MasterSound id -> {row, sheet, cue, categories, volume, busSends, layers[{file, sampleRate, samples,
+                loopStart, loopEnd, loopFlag, volume, busSends}], lengthMs}; the cue structure (sequence -> tracks ->
+                synth -> waveform) is read from the ACB (nnnotes.acb; command 65 categories, 146 volume, 111 bus send)
+  categories    CRI category volumes for a fresh profile (SoundVolumeSettings x AppConfigDefaultData)
+  react         the ACF's REACT (ducking) entries between live categories
+  music         the BGM sound id and PlayMusic volume
+  noteSe        LiveNoteSeType -> sound id / volume / mute for the default preset (LiveSettingCreator.CreateSESettings);
+                with liveoptions.LiveOptions offering note sound sets also `groups`: set id -> LiveNoteSeType ->
+                sound id (MasterLiveNoteSe), every offered set's sounds decoded as well
+  liveSe        LiveSeType -> sound id (MasterLiveSe); `sounds` has those of LIVE_SE_SOUNDS: the start and finish
+                cheers and the finish direction of every result (the one a live ends with depends on how it is played)
+  timeline      intro / end timings the runtime needs
+  voice         the start / finish character voice rule and the voice character the caller chose (none by default)
+
+Cue sheets come through `cri` (any of its layouts; the note SE / live SE / voice sheets are embedded ACBs);
+each cue layer maps to its vgmstream stream by `streams.json` (memory AWB order). A sheet already decoded into
+`<out>/audio/<sheet>/` (the BGM by score.py) is reused.
+"""
+from __future__ import annotations
+
+import struct
+import zipfile
+from pathlib import Path
+
+from .acb import commands as _commands, tables as _tables, u16s as _u16s
+from .catalog import Catalog
+from .jsonio import write_json
+from .liveoptions import LiveOptions
+from .player import PlayerData
+from .score import master_table
+from . import cri
+
+ACF_IN_APK = "assets/Cri/Sound/Sirius.acf"
+
+# App.Master.LiveNoteSeType / LiveSeType
+NOTE_SE_TYPES = {1: "InVain", 2: "Good", 3: "Great", 4: "Perfect", 5: "Flick", 6: "FlickDirection", 7: "Slide",
+                 8: "Just", 9: "Trace", 10: "SlideConnect", 11: "GekisouTap", 12: "GekisouFlick",
+                 13: "GekisouFlickDirection", 14: "GekisouSlide"}
+LIVE_SE_TYPES = {1: "GekisouCountDown", 2: "LuckHit", 3: "LuckSuperHit", 4: "LuckCritical", 5: "LuckMiss",
+                 6: "LuckRushDouble", 7: "LuckRushTriple", 8: "LuckRushMax", 9: "StartCheers", 10: "FinishCheers",
+                 11: "GekisouFirstCheers", 12: "GekisouOthersCheers", 13: "LiveClearDirection",
+                 14: "FullComboDirection", 15: "AssistFullComboDirection", 16: "AllPerfectDirection"}
+# SoundSettingsExtensions.ToOptionItemType (its constant table: note SE type 1..14 -> volume OptionItemType)
+NOTE_SE_VOLUME_ITEM = [431, 433, 433, 433, 435, 437, 439, 433, 441, 439, 451, 453, 455, 457]
+# OptionSoundUtility.GetMuteTypeForVolume: volume item -> mute item (OptionItemType 431..459 -> 460..470)
+NOTE_SE_MUTE_ITEM = {431: 460, 433: 461, 435: 462, 437: 463, 439: 464, 441: 465, 451: 466, 453: 467, 455: 468,
+                     457: 469, 459: 470}
+# LiveSettingCreator.BuildIndividualNoteSeDictionary: the sound set item (OptionItemType) of each note SE type
+NOTE_SE_ID_ITEM = {1: 430, 2: 432, 3: 432, 4: 432, 8: 432, 5: 434, 6: 436, 7: 438, 10: 438, 9: 440, 11: 450,
+                   12: 452, 13: 454, 14: 456}
+# live SE whose sounds a live directory carries: the start / finish cheers (9, 10) and the finish direction of every
+# result (LivePlayingStateNodeBase.PlayFinishVoiceAndCheer: after the result's voice and the finish cheer, 16
+# AllPerfectDirection, else 14 FullComboDirection, else 15 AssistFullComboDirection, else 13 LiveClearDirection; none
+# when the life is below 1), in type order
+LIVE_SE_SOUNDS = (9, 10, 13, 14, 15, 16)
+
+
+def _params(cmds, categories: dict[int, str], buses: list[str]) -> dict:
+    """Parameters of one command list. 65 = category ids, 146 = volume, 111 = bus send (index into the ACB's
+    StringValueTable bus names, level / 10000). Other codes are kept as hex, uninterpreted."""
+    d = {"categories": [], "volume": 1.0, "busSends": {}, "other": {}}
+    for code, v in cmds:
+        if code == 65:
+            d["categories"] += [categories[struct.unpack_from(">I", v, i)[0]] for i in range(0, len(v), 4)]
+        elif code == 146:
+            d["volume"] *= struct.unpack(">f", v)[0]
+        elif code == 111:
+            bus, level = struct.unpack(">HH", v)
+            d["busSends"][buses[bus]] = level / 10000
+        elif code in (0, 2000):
+            pass
+        else:
+            d["other"][str(code)] = v.hex()
+    return d
+
+
+def acb_cues(acb: bytes) -> dict[str, dict]:
+    """{cueName: cue data} of an ACB whose cues are sequences of tracks that note-on one synth each (the only shape
+    in the live sheets; anything else raises)."""
+    top, T = _tables(acb)
+    categories = {r["Id"]: r["Name"] for r in T.get("AcfReferenceTable", []) if r["Type"] == 3}
+    buses = [r["StringValue"] for r in T.get("StringValueTable", [])]
+    names = {r["CueIndex"]: r["CueName"] for r in T["CueNameTable"]}
+
+    def cmd(table, index):
+        return [] if index == 65535 else _commands(T[table][index]["Command"])
+
+    out = {}
+    for ci, c in enumerate(T["CueTable"]):
+        name = names[ci]
+        if c["ReferenceType"] != 3:
+            raise ValueError(f"{name}: cue reference type {c['ReferenceType']} (only sequences handled)")
+        seq = T["SequenceTable"][c["ReferenceIndex"]]
+        if seq["Type"] != 0:
+            raise ValueError(f"{name}: sequence type {seq['Type']} (only polyphonic handled)")
+        sp = _params(cmd("SeqCommandTable", seq["CommandIndex"]), categories, buses)
+        layers = []
+        for ti in _u16s(seq["TrackIndex"]):
+            tr = T["TrackTable"][ti]
+            tp = _params(cmd("TrackCommandTable", tr["CommandIndex"]), categories, buses)
+            ons = [v for code, v in cmd("TrackEventTable", tr["EventIndex"]) if code == 2000]
+            if len(ons) != 1:
+                raise ValueError(f"{name}: track {ti} has {len(ons)} note-ons")
+            kind, si = struct.unpack(">HH", ons[0][:4])
+            if kind != 2:
+                raise ValueError(f"{name}: track {ti} note-on kind {kind}")
+            syn = T["SynthTable"][si]
+            yp = _params(cmd("SynthCommandTable", syn["CommandIndex"]), categories, buses)
+            items = [struct.unpack_from(">HH", syn["ReferenceItems"], i) for i in range(0, len(syn["ReferenceItems"]), 4)]
+            if syn["Type"] != 0 or len(items) != 1 or items[0][0] != 1:
+                raise ValueError(f"{name}: synth {si} type {syn['Type']} items {items}")
+            w = T["WaveformTable"][items[0][1]]
+            if w["Streaming"] != 0:
+                raise ValueError(f"{name}: streamed waveform (memory AWB expected)")
+            layers.append({"awbId": w["MemoryAwbId"], "samples": w["NumSamples"], "loopFlag": w["LoopFlag"],
+                           "volume": tp["volume"] * yp["volume"], "busSends": {**tp["busSends"], **yp["busSends"]},
+                           "trackOther": tp["other"], "synthOther": yp["other"]})
+        out[name] = {"cueId": c["CueId"], "lengthMs": c["Length"], "categories": sp["categories"],
+                     "volume": sp["volume"], "busSends": sp["busSends"], "sequenceOther": sp["other"],
+                     "acbVolume": top.get("AcbVolume", 1.0), "layers": layers}
+    return out
+
+
+def acf_info(apk: Path) -> dict:
+    """Categories, buses and REACT entries of the game's ACF (`assets/Cri/Sound/Sirius.acf` in the APK)."""
+    with zipfile.ZipFile(apk) as z:
+        top, T = _tables(z.read(ACF_IN_APK))
+    cat_names = {r["Index"]: r["Name"] for r in T["CategoryNameTable"]}
+    cats = {}
+    for r in T["CategoryTable"]:
+        if r["CommandIndex"] != 65535:
+            raise ValueError(f"ACF category {cat_names[r['Id']]} has commands (default volume) - not handled")
+        cats[cat_names[r["Id"]]] = {"id": r["Id"], "group": r["GroupIndex"]}
+    bus_names = [r["StringValue"] for r in T["BusNameTable"]]
+    buses = [{"name": bus_names[b["BusNameIndex"]], "volume": b["Volume"], "fx": b["NumFxs"]} for b in T["BusTable"]]
+    react = [{"name": r["REACTName"], "src": cat_names[r["Src"]], "dest": cat_names[r["Dest"]], "level": r["Level"],
+              "decrementMs": r["DecrementTime"], "incrementMs": r["IncrementTime"], "holdType": r["HoldType"],
+              "holdMs": r["HoldTime"], "startCurve": [r["StartCurveType"], r["StartCurveStrength"]],
+              "endCurve": [r["EndCurveType"], r["EndCurveStrength"]], "parameterId": r["ParameterId"],
+              "targetType": r["TargetType"]} for r in T.get("ReactTable", [])]
+    return {"name": top["Name"], "categories": cats, "buses": buses, "react": react}
+
+
+# --------------------------------------------------------------------------- game settings
+def _player_mono(player: PlayerData, cls: str) -> dict:
+    hits = []
+    for o in player.env.objects:
+        if o.type.name != "MonoBehaviour":
+            continue
+        try:
+            if player.script(o)[2] != cls:
+                continue
+        except Exception:        # MonoBehaviours without a resolvable script are not ours
+            continue
+        hits.append(player.mono(o))
+    if len(hits) != 1:
+        raise RuntimeError(f"{cls}: {len(hits)} objects in the player data")
+    return hits[0]
+
+
+def category_volumes(player: PlayerData) -> dict:
+    """Fresh-profile CRI category volumes: `<Cat>` = SoundVolumeSettings.DefaultVolume x 1.0
+    (SoundManager.Boot ChangeVolume("All", 1)); `Live<X>Config` = LocalCacheData live volume = AppConfigDefaultData
+    (AppConfig.UpdateLiveSoundVolumeConfig); Bgm/Se/VoiceConfig = system option 400-402 / 100 (preset 1: 1.0)."""
+    svs = {e["CategoryName"]: e["DefaultVolume"] for e in _player_mono(player, "SoundVolumeSettings")["_collection"]}
+    acd = _player_mono(player, "AppConfigDefaultData")["_defaultData"]
+    live = {"LiveBgm": "LiveBgmSoundVolume", "LiveSe": "LiveSeSoundVolume", "LiveVoice": "LiveVoiceSoundVolume",
+            "LiveNotesSe": "LiveNotesSeSoundVolume"}
+    out = dict(svs)
+    for cat, field in live.items():
+        out[cat + "Config"] = acd[f"<{field}>k__BackingField"]
+    return out
+
+
+def _option(rows: list[dict], preset: int, item: int) -> str:
+    hit = [r["_valueString"] for r in rows if r["_presetId"] == preset and r["_optionItemType"] == item]
+    if len(hit) != 1:
+        raise KeyError(f"MasterOptionDefault preset {preset} item {item}: {len(hit)} rows")
+    return hit[0]
+
+
+def note_se_groups(master: Path) -> dict[int, dict[int, int]]:
+    """MasterLiveNoteSe: sound set (_groupID) -> LiveNoteSeType -> sound id."""
+    out: dict[int, dict[int, int]] = {}
+    for r in master_table(master, "MasterLiveNoteSe"):
+        out.setdefault(r["_groupID"], {})[r["_liveNoteSeType"]] = r["_seId"]
+    return out
+
+
+def _volume(opt: list[dict], preset: int, item: int) -> float:
+    """OptionSoundUtility.GetIndividualNoteSeVolume: 0 when the item's mute (GetMuteTypeForVolume) is on, else
+    clamp01(value / 100)."""
+    if _option(opt, preset, NOTE_SE_MUTE_ITEM[item]).upper() == "TRUE":
+        return 0.0
+    return min(max(int(_option(opt, preset, item)) / 100.0, 0.0), 1.0)
+
+
+def note_se_settings(master: Path, preset: int = 1, groups: tuple = ()) -> dict:
+    """LiveSettingCreator.CreateSESettings for a fresh profile (option preset `preset`): pattern mode takes the
+    MasterLiveNoteSe rows of the set NoteSePatternId (420); UseIndividualNoteSe (421) takes, per note SE type, the
+    row of the set its sound item names (BuildIndividualNoteSeDictionary; a type whose set has no row for it has no
+    entry). `groups`: sound set ids whose tables are written as `groups` as well (the sets a viewer may choose)."""
+    opt = master_table(master, "MasterOptionDefault")
+    table = note_se_groups(master)
+    group = int(_option(opt, preset, 420))
+    individual = _option(opt, preset, 421).upper() == "TRUE"
+    if individual:
+        types = {}
+        for t, item in NOTE_SE_ID_ITEM.items():
+            se = table.get(int(_option(opt, preset, item)), {}).get(t)
+            if se is not None:
+                types[t] = se
+    else:
+        types = dict(table.get(group, {}))
+    volumes, mutes = {}, {}
+    for t in range(1, 15):
+        item = NOTE_SE_VOLUME_ITEM[t - 1]
+        mute = _option(opt, preset, NOTE_SE_MUTE_ITEM[item]).upper() == "TRUE"
+        # GetIndividualNoteSeVolume (mute -> 0) / GetNoteSeMute (GetMuteTypeForVolume)
+        volumes[t], mutes[t] = _volume(opt, preset, item), mute
+    out = {"preset": preset, "patternId": group, "useIndividualNoteSe": individual,
+           "types": {str(k): types[k] for k in sorted(types)}, "typeNames": NOTE_SE_TYPES,
+           "volumes": {str(k): v for k, v in volumes.items()}, "mutes": {str(k): v for k, v in mutes.items()},
+           "gekisouTraceVolume": _volume(opt, preset, 459)}
+    if groups:
+        missing = [g for g in groups if g not in table]
+        if missing:
+            raise KeyError(f"MasterLiveNoteSe has no rows of sound set(s) {missing}")
+        out["groups"] = {str(g): {str(t): table[g][t] for t in sorted(table[g])} for g in groups}
+    return out
+
+
+# --------------------------------------------------------------------------- extraction
+def _decode(cat: Catalog, sheet: str, out_dir: Path, fmt: str, flac_level: int) -> list[dict]:
+    """Decode a cue sheet into <out>/audio/<sheet>/ (reusing an existing decode) and return its stream list."""
+    d = out_dir / "audio" / sheet
+    if not (d / "streams.json").exists():
+        cri.decode(cat, sheet, d, fmt=fmt, flac_level=flac_level)
+    import json
+    return json.loads((d / "streams.json").read_text(encoding="utf-8"))
+
+
+def _sound_entry(row: dict, sheet: str, cue: dict, streams: list[dict], cue_name: str) -> dict:
+    layers = []
+    for L in cue["layers"]:
+        s = streams[L["awbId"]]                     # vgmstream streams follow the memory AWB order
+        if s["name"] != cue_name or abs(s["samples"] - L["samples"]) > 8:
+            raise RuntimeError(f"{sheet}/{cue_name}: AWB {L['awbId']} -> stream {s} does not match")
+        layers.append({"file": f"audio/{sheet}/{s['file']}", "stream": s["stream"], "awbId": L["awbId"],
+                       "sampleRate": s["sampleRate"], "channels": s["channels"], "samples": s["samples"],
+                       "loopStart": s.get("loopStart"), "loopEnd": s.get("loopEnd"), "loopFlag": L["loopFlag"],
+                       "volume": L["volume"], "busSends": L["busSends"],
+                       "other": {"track": L["trackOther"], "synth": L["synthOther"]}})
+    return {"row": row, "sheet": sheet, "cue": cue_name, "category": row["_category"],
+            "categories": cue["categories"], "volume": cue["volume"] * cue["acbVolume"], "busSends": cue["busSends"],
+            "lengthMs": cue["lengthMs"], "other": cue["sequenceOther"], "layers": layers}
+
+
+def extract(cat: Catalog, master: Path, player: PlayerData, music_id: int, out_dir: Path,
+            fmt: str = "flac", voice_character: int | None = None, options: LiveOptions = LiveOptions(), *,
+            flac_level: int = cri.FLAC_LEVEL) -> dict:
+    """Decode the live's sound cue sheets and write <out>/audio/live-audio.json. Returns a summary.
+    voice_character: None = no character voice (the game picks the voice from the player's deck; there is no rule
+    without a deck). `options`: the note sound sets it offers are written as noteSe.groups, their sounds decoded
+    after the default ones. `flac_level`: ffmpeg's compression level of the FLAC files (cri.decode)."""
+    out_dir = Path(out_dir)
+    if cat.apk is None:
+        raise RuntimeError("liveaudio needs the Catalog opened with apk= (ACF, HCA key)")
+    sounds = {str(r["_id"]): r for r in master_table(master, "MasterSound")}
+    sheets = {r["_id"]: r["_cueSheetName"] for r in master_table(master, "MasterSoundCueSheet")}
+    music = [r for r in master_table(master, "MasterLiveMusic") if r["_id"] == music_id]
+    if len(music) != 1:
+        raise KeyError(f"MasterLiveMusic {music_id}")
+    music_sound = music[0]["_musicSoundID"]
+    nse = note_se_settings(master, groups=options.se_patterns)
+    live_se = {r["_liveSeType"]: r["_seId"] for r in master_table(master, "MasterLiveSe")}
+    want = [music_sound] + sorted(set(nse["types"].values())) + [live_se[t] for t in LIVE_SE_SOUNDS]
+    voice = {"decision": "caller", "character": voice_character,
+             "rule": "LotteryStartVoice: random deck member, random MasterLiveStartCharacterVoice row of that "
+                     "character; finish voice from LotteryFinishVoice; no deck -> undefined",
+             "startVoiceSoundIds": []}
+    if voice_character is not None:
+        rows = [r for r in master_table(master, "MasterLiveStartCharacterVoice")
+                if r["_characterId"] == voice_character]
+        voice["startVoiceSoundIds"] = [r["_voiceSoundId"] for r in rows]
+        want += voice["startVoiceSoundIds"]
+    for se in sorted({v for g in nse.get("groups", {}).values() for v in g.values()}):
+        if se not in want:
+            want.append(se)
+
+    by_sheet: dict[str, list[int]] = {}
+    for sid in want:
+        r = sounds[str(sid)]
+        by_sheet.setdefault(sheets[r["_soundCueSheetID"]], []).append(sid)
+    entries, decoded = {}, {}
+    for sheet, ids in by_sheet.items():
+        acb, layout = cri.acb_data(cat, sheet)
+        cues = acb_cues(acb["acb"])
+        streams = _decode(cat, sheet, out_dir, fmt, flac_level)
+        decoded[sheet] = {"layout": layout, "cues": len(cues), "streams": len(streams)}
+        for sid in ids:
+            r = sounds[str(sid)]
+            if r["_isRandomPitch"]:
+                raise NotImplementedError(f"sound {sid}: random pitch")
+            entries[str(sid)] = _sound_entry(r, sheet, cues[r["_cueName"]], streams, r["_cueName"])
+
+    acf = acf_info(cat.apk)
+    doc = {
+        "musicId": music_id,
+        "spec": "nnnotes.liveaudio",
+        "sounds": entries,
+        "categories": category_volumes(player),
+        "acf": {"name": acf["name"], "buses": acf["buses"], "categories": acf["categories"]},
+        "react": acf["react"],
+        "music": {"soundId": music_sound, "volume": 1.0, "startTimeSec": 0.0},
+        "noteSe": nse,
+        "liveSe": {str(k): v for k, v in sorted(live_se.items())}, "liveSeNames": LIVE_SE_TYPES,
+        "timeline": {"startCheerDelaySec": 1.0, "playVoiceSignalSec": 1.483333, "startCheerStopFadeSec": 1.0,
+                     "finishCheerStopFadeSec": 1.0},
+        "voice": voice,
+        "decoded": decoded,
+    }
+    write_json(out_dir / "audio" / "live-audio.json", doc)
+    return {"index": "audio/live-audio.json", "sheets": sorted(by_sheet), "sounds": len(entries),
+            "musicSoundId": music_sound}