Muninn has one body: drop the workspace copy
The three muninn crates, their seventeen actuator scripts, the two Raven capture-mux wrappers that called one of them, and the two Muninn docs all leave this workspace. GameCult/Muninn has carried them since 2026-09-09 and has moved on (media stream advertisement, receivers dialling the producer); this copy was a fork drifting behind under the same name, and gamecult-ops now binds every Muninn target to the Muninn repository. Odin keeps the Muninn records in odin-core until they are moved; that is the remaining piece of the extraction. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
parent
1ff6a323de
commit
d41c744b2e
34 changed files with 4 additions and 22638 deletions
|
|
@ -109,8 +109,8 @@ delivery, or renderer layout. Keepalive loops belong in Idunn, not Odin's
|
|||
coordinator or individual daemons.
|
||||
|
||||
Muninn is the portable local telemetry Verse assembler. Its Rust body lives in
|
||||
`crates/muninn-daemon` and publishes `muninn.telemetry_surface.v1` through
|
||||
CultMesh/CultCache. Muninn may run on Raven, Nightwing, Starfire, or any future
|
||||
the `GameCult/Muninn` repository and publishes `muninn.telemetry_surface.v1`
|
||||
through CultMesh/CultCache. Muninn may run on Raven, Nightwing, Starfire, or any future
|
||||
device body. It names locally accessible telemetry affordances: screen capture,
|
||||
loopback audio, microphones, cameras, and future sensors. Muninn does not start
|
||||
expensive capture streams merely because the daemon is alive. The default
|
||||
|
|
|
|||
|
|
@ -1,374 +0,0 @@
|
|||
# Muninn Media Streaming
|
||||
|
||||
Muninn live A/V is the stress organ for CultMesh transport. The goal is not
|
||||
"make OBS show something once." The goal is encoded game video and audio moving
|
||||
between nearby PCs at LAN speed with bounded latency, observable ownership, and
|
||||
transport behavior that teaches CultMesh how to carry hot media.
|
||||
|
||||
## Objective
|
||||
|
||||
Raven Muninn captures screen video and Realtek loopback audio, encodes them with
|
||||
hardware-first low-latency settings, publishes them through CultNet/CultMesh
|
||||
media streams, and lets the Muninn OBS plugin render the stream without owning
|
||||
capture, daemon lifecycle, or transport truth.
|
||||
|
||||
## Current Mechanism
|
||||
|
||||
The current Raven A/V path is a compatibility path:
|
||||
|
||||
1. OBS reads Raven's `muninn.obs_stream_catalog` from the synced CultCache
|
||||
store.
|
||||
2. The OBS plugin sends a typed `muninn.capture_stream_command` to Raven's
|
||||
Muninn daemon over CultNet RUDP.
|
||||
3. Raven Muninn `serve` owns command acceptance and spawns a daemon-owned
|
||||
activation child for the requested stream.
|
||||
4. The activation child starts WASAPI loopback capture and FFmpeg.
|
||||
5. FFmpeg muxes encoded video and audio into MPEG-TS on stdout.
|
||||
6. Muninn slices that byte stream into fixed-size chunks and sends those chunks
|
||||
over the RUDP `media` channel.
|
||||
7. The OBS plugin forwards received bytes into a local FFmpeg source.
|
||||
|
||||
That path proved activation, capture, hardware encode, and cross-machine
|
||||
delivery. It is not the final media architecture. MPEG-TS byte chunks over an
|
||||
unordered lossy hot path give CultMesh no frame identity, no deadline, no media
|
||||
dependency graph, and no clean way to choose between retransmit, conceal,
|
||||
discard, keyframe request, or audio/video resync.
|
||||
|
||||
## Invariants
|
||||
|
||||
- Muninn owns local capture and stream activation for the machine body where
|
||||
the sensors live.
|
||||
- OBS and Mimir are consumers. They may request a stream and report receiver
|
||||
health, but they do not start capture by implication and do not own Raven
|
||||
daemon state.
|
||||
- Idunn owns daemon supervision and health pressure. It does not infer that
|
||||
liveness means screen/audio capture should be burning.
|
||||
- CultMesh owns live media stream semantics: stream identity, frame identity,
|
||||
timestamps, deadlines, dependencies, channel policy, and receiver feedback.
|
||||
- CultCache records are receipts, catalog entries, and operator/debug state.
|
||||
They are not the hot media lane.
|
||||
- Audio and video have separate clocks and recovery policy. They may share a
|
||||
session, but they must not be hidden inside an opaque transport byte soup.
|
||||
- Transport reliability is deadline-bound. Late media is damage, not treasure.
|
||||
|
||||
## Intended Change
|
||||
|
||||
Replace "MPEG-TS stdout sliced into RUDP packets" with "codec access units and
|
||||
audio packets published as typed CultMesh media frames."
|
||||
|
||||
The stream owner should emit media documents shaped around decisions the
|
||||
transport and decoder actually need:
|
||||
|
||||
```text
|
||||
muninn.media_video_access_unit.v1
|
||||
stream_id
|
||||
session_id
|
||||
frame_id
|
||||
codec
|
||||
pts_ticks
|
||||
duration_ticks
|
||||
timebase_num
|
||||
timebase_den
|
||||
keyframe
|
||||
dependency_frame_id
|
||||
deadline_ticks
|
||||
chunk_index
|
||||
chunk_count
|
||||
payload
|
||||
|
||||
muninn.media_audio_packet.v1
|
||||
stream_id
|
||||
session_id
|
||||
packet_id
|
||||
codec
|
||||
pts_ticks
|
||||
duration_ticks
|
||||
timebase_num
|
||||
timebase_den
|
||||
deadline_ticks
|
||||
payload
|
||||
|
||||
muninn.media_receiver_feedback.v1
|
||||
stream_id
|
||||
session_id
|
||||
receiver_id
|
||||
highest_decodable_frame_id
|
||||
missing_frame_ids
|
||||
missing_video_chunk_keys
|
||||
late_frame_ids
|
||||
requested_keyframe
|
||||
jitter_us
|
||||
decode_queue_us
|
||||
```
|
||||
|
||||
The exact schema names can move when promoted into the shared document catalog,
|
||||
but the ownership shape should not: frame/access-unit identity is load-bearing.
|
||||
|
||||
## Authority Map
|
||||
|
||||
- Owner: Muninn capture runtime owns source capture, encode configuration, and
|
||||
emission of video access units plus audio packets for a requested stream.
|
||||
- Inputs: explicit `muninn.capture_stream_command`, local capture devices,
|
||||
encoder capabilities, receiver feedback, stream policy, and Idunn-supervised
|
||||
daemon runtime state.
|
||||
- Outputs: typed active stream receipts in CultCache, CultMesh media frames over
|
||||
CultNet RUDP, and typed receiver/transport health receipts.
|
||||
- Derived state: OBS catalog entries are discovery hints; local FFmpeg bridge
|
||||
URLs are compatibility lowering details; packet counters and logs are
|
||||
observability only.
|
||||
- Forbidden writers: OBS source settings, local UDP bridge behavior, scheduled
|
||||
task wrappers, health scripts, and replayed command receipts must not decide
|
||||
capture state, stream identity, frame order, or media repair policy.
|
||||
- Shared paths: direct operator requests, OBS plugin requests, future Mimir
|
||||
requests, restart recovery, and reconnect recovery must all publish the same
|
||||
typed capture command and consume the same active stream receipts.
|
||||
- Deletion line: delete the hot-path assumption that a media stream is an
|
||||
MPEG-TS byte stream. Keep it only as a named compatibility lowering until the
|
||||
OBS receiver can consume typed media frames directly.
|
||||
|
||||
## Boring Stream Discovery Contract
|
||||
|
||||
The desired operator experience is boring: OBS asks the Verse for Muninns, the
|
||||
plugin shows live sources, and a selected source either activates or reports the
|
||||
specific owner that refused it. No local plugin fallback may invent Raven
|
||||
devices. A fake `display:0` or Realtek loopback row is worse than an empty list
|
||||
because it makes stale state look selectable.
|
||||
|
||||
Live ownership:
|
||||
|
||||
- Owner: Muninn `serve` owns source inventory for the body where the devices
|
||||
exist. It publishes video and audio source ids, labels, command boundary,
|
||||
media profile, and current active sessions.
|
||||
- Inputs: local display/audio enumeration, explicit configured source hints,
|
||||
daemon health, and accepted stream commands.
|
||||
- Outputs: `muninn.telemetry_surface.v1`, `gamecult.eve.provider_advertisement.v1`,
|
||||
`muninn.command_boundary.v1`, `muninn.transport_profile.v1`, active
|
||||
`muninn.capture_stream.v1` receipts, and the temporary
|
||||
`muninn.obs_stream_catalog.v1` compatibility record.
|
||||
- Derived state: the OBS dropdown is a lowering of discovered Muninn state. It
|
||||
is not an inventory owner, activation owner, or health owner.
|
||||
- Forbidden writers: OBS defaults, local hard-coded device names, synced stale
|
||||
CultCache mirrors, scheduled-task launchers, and previous activation receipts
|
||||
must not create selectable devices or active streams.
|
||||
- Shared paths: initial OBS load, refresh button, periodic refresh, source
|
||||
selection, reconnect, and OBS restart must all read the same live-discovered
|
||||
source list and issue the same typed capture command when activation is
|
||||
needed.
|
||||
- Deletion line: the plugin may display `discovery missing`, but it must not
|
||||
synthesize `Display 1` or `Realtek loopback` as if Raven advertised them.
|
||||
Until Odin/Verse discovery is the direct plugin input, the OBS catalog remains
|
||||
a compatibility projection of Muninn-owned live state, not its own truth.
|
||||
Compatibility store fallback is allowed only as availability fallback: the
|
||||
plugin must use the first current store that yields Muninn telemetry and must
|
||||
not merge stale stores into a more attractive fake inventory.
|
||||
A store older than the Muninn health freshness budget is not a discovery
|
||||
source; it is an outage receipt.
|
||||
|
||||
This contract also splits the media session truth:
|
||||
|
||||
- Video session: selected video source id, encoder profile, bitrate, frame
|
||||
timestamps, access-unit ids, keyframe policy, feedback pressure, and video
|
||||
receiver queue.
|
||||
- Audio session: selected audio source id, sample format, packet timestamps,
|
||||
reorder budget, continuity/drop policy, and OBS audio output cadence.
|
||||
- Combined OBS source: a convenience lowering that may request one video session
|
||||
and one audio session together. It does not merge their clocks or transport
|
||||
state into one opaque "A/V target".
|
||||
|
||||
## Known-Good Checkpoint (2026-06-23)
|
||||
|
||||
The current system is in a usable compatibility state worth preserving before
|
||||
the next transport experiment.
|
||||
|
||||
What is working:
|
||||
|
||||
- Raven Muninn runs continuously as the capture owner and accepts stream
|
||||
activation over CultNet RUDP.
|
||||
- OBS on Starfire shows the live-discovered Muninn source inventory instead of
|
||||
synthesizing fake devices from stale local defaults.
|
||||
- Video and audio sessions activate separately through the combined OBS source
|
||||
lowering and the stream comes up cleanly again after reconnect.
|
||||
- The OBS plugin currently receives the temporary live
|
||||
`muninn.obs_stream_catalog.v1` projection over UDP `17874` and uses it as the
|
||||
live discovery source before any CultCache fallback.
|
||||
|
||||
Current compatibility details:
|
||||
|
||||
- Raven command ingress is currently bound to `0.0.0.0:17883`.
|
||||
- Starfire OBS listens for the temporary live OBS catalog on UDP `17874`.
|
||||
- The daemon `serve` loop must continue publishing the OBS catalog while idle;
|
||||
otherwise OBS falls back to stale store state and reports `discovery-missing`
|
||||
or shows dead inventory.
|
||||
- The current OBS plugin is still a compatibility client. It does not yet host
|
||||
the Rust CultMesh runtime directly and it is not yet consuming Odin/Verse
|
||||
discovery as a first-class Verse client.
|
||||
|
||||
Known debt that remains intentionally visible:
|
||||
|
||||
- Idunn health publication can still time out independently of the media path.
|
||||
That is operational debt, not proof that Muninn discovery or streaming is
|
||||
down.
|
||||
- The OBS catalog is still a temporary projection. The boring end state is live
|
||||
Verse discovery with no plugin-owned catalog receiver and no stale store
|
||||
merge behavior.
|
||||
|
||||
## Codec Direction
|
||||
|
||||
Use vendor hardware encode before inventing a codec. NVIDIA's practical answer
|
||||
in this space is NVENC/NVDEC, low-latency encode presets, high LAN bitrate,
|
||||
short GOP or intra-refresh, no B-frames, no lookahead, and application-level
|
||||
transport that understands frame deadlines.
|
||||
|
||||
Shipping order:
|
||||
|
||||
1. H.264 NVENC low-latency as the compatibility baseline for broad decoder
|
||||
support, simple failure analysis, and OBS bridge stability.
|
||||
2. HEVC NVENC low-latency when Raven encode and OBS decode both prove the
|
||||
target latency budget.
|
||||
3. AV1 NVENC only after the exact Raven-to-OBS path proves encode, decode, and
|
||||
queue latency inside budget. AV1 can be the quality/bandwidth winner, but it
|
||||
must earn the low-latency lane on our hardware instead of getting promoted by
|
||||
codec fashion.
|
||||
|
||||
The codec should produce elementary video access units, not a muxed MPEG-TS
|
||||
program. Audio should use Opus low-delay packets unless the OBS lowering needs
|
||||
a temporary PCM/AAC compatibility bridge.
|
||||
|
||||
Recommended first LAN profile:
|
||||
|
||||
- Profile id: `muninn.rudp.low_latency_h264_lan.v1`.
|
||||
- Video: H.264 NVENC, `p1`, ultra-low-latency tune, CBR high enough that LAN
|
||||
bandwidth is not the constraint, no B-frames, no lookahead, short GOP or
|
||||
intra-refresh, periodic IDR/keyframe on feedback pressure.
|
||||
- VBV: derive `bufsize` from roughly one frame of bitrate
|
||||
(`bitrate_kbps / framerate`) instead of a large fixed encoder reservoir.
|
||||
The point is bounded latency, not hoarding compressed video in a nicer hat.
|
||||
- Audio: Opus low-delay when OBS lowering can consume it directly; otherwise a
|
||||
temporary PCM/AAC bridge with separate packet identity and clock.
|
||||
- Transport: payload elementary access units as typed media records, never a
|
||||
muxed container as the unit of truth.
|
||||
- Packet size: default typed media chunks are `480` bytes. That leaves headroom
|
||||
for CultNet/MessagePack/RUDP headers inside a normal Ethernet MTU so the OBS
|
||||
bridge does not depend on IP fragmentation or private RUDP fragment
|
||||
reassembly. The sender also sets CultNet RUDP `max_fragment_bytes` to `1431`
|
||||
bytes (`1472` byte IPv4 UDP payload budget minus `36` RUDP fixed header bytes
|
||||
minus the five-byte `media` channel id), so oversized typed records fragment
|
||||
in CultNet deliberately instead of falling through to accidental IP
|
||||
fragmentation.
|
||||
- Resend cadence: sender RUDP media resends are scheduled every `5` ms while
|
||||
the packet is still inside the `75` ms reliable-expiry budget.
|
||||
- Control: sender may adapt bitrate, keyframe cadence, chunk size, and playout
|
||||
budget from receiver feedback; the receiver must not silently stretch latency
|
||||
to preserve visual perfection.
|
||||
- Receiver URL policy: RUDP stream URLs carry `profile`,
|
||||
`sender_resend_delay_ms`, `reliable_expire_after_ms`,
|
||||
`assembly_deadline_ms`, and `gap_wait_ms` so the OBS bridge receives timing
|
||||
budget from Muninn's stream profile instead of hard-coding receiver policy
|
||||
privately.
|
||||
|
||||
### Motion Vectors And Reconstruction
|
||||
|
||||
Do not make CultMesh a bespoke game-streaming codec in the first shipping path.
|
||||
The motion-vector/delta idea is real, but it belongs as an augmentation around
|
||||
the hardware codec, not as the primary authority.
|
||||
|
||||
NVIDIA's relevant public pattern is:
|
||||
|
||||
- NVENC/NVDEC for hardware video encode and decode.
|
||||
- Low-latency encode tuning, high refresh rate, adaptive bitrate, and explicit
|
||||
network/frame timing for cloud gaming.
|
||||
- Foveated streaming for bandwidth reduction when a trusted focus region exists.
|
||||
- Optical Flow / motion estimation hardware for interpolation, extrapolation,
|
||||
analysis, or concealment experiments.
|
||||
|
||||
For Muninn, that means:
|
||||
|
||||
- If we only have desktop capture pixels, trust NVENC for motion estimation and
|
||||
compression. Do not compute our own patch stream before the codec has failed a
|
||||
measured requirement.
|
||||
- If a game or renderer we control can expose motion vectors, depth, regions of
|
||||
interest, or dirty rectangles, publish them as optional sideband media hints.
|
||||
They may guide encoder ROI, decoder concealment, frame extrapolation, or
|
||||
foveated quality allocation. They do not replace the encoded video access
|
||||
unit unless a separate research path proves that decoder under the same OBS
|
||||
latency budget.
|
||||
- Stochastic reconstruction is allowed only inside a bounded playout budget.
|
||||
When the deadline expires, the receiver displays the best available frame,
|
||||
conceals damage, or requests a keyframe. It must not preserve dead packets by
|
||||
growing latency.
|
||||
|
||||
Useful references for this direction:
|
||||
|
||||
- NVIDIA Video Codec SDK presets describe low-latency and ultra-low-latency
|
||||
tuning plus preset tradeoffs for encoder tools such as GOP structure,
|
||||
B-frames, and lookahead:
|
||||
<https://developer.nvidia.com/blog/introducing-video-codec-sdk-10-presets/>
|
||||
- NVIDIA CloudXR publicly frames low-latency spatial streaming around NVENC,
|
||||
adaptive bitrate, foveated streaming, diagnostics, and bidirectional data
|
||||
channels:
|
||||
<https://docs.nvidia.com/cloudxr-sdk/latest/overview/overview.html>
|
||||
- NVIDIA's Optical Flow SDK exposes hardware motion vectors for real-time
|
||||
interpolation/extrapolation and related video processing:
|
||||
<https://developer.nvidia.com/optical-flow-sdk>
|
||||
|
||||
## CultNet RUDP Media Policy
|
||||
|
||||
The RUDP `media` channel should become a media-aware lane, not merely a reliable
|
||||
unordered byte lane.
|
||||
|
||||
Required behavior:
|
||||
|
||||
- Frame-level fragmentation and reassembly keyed by `(stream_id, session_id,
|
||||
frame_id)`.
|
||||
- Deadline-aware retransmission: resend while useful, drop when the playout
|
||||
budget is gone.
|
||||
- Receiver feedback that can NACK missing chunks, request a keyframe, and
|
||||
report jitter/decode queue pressure.
|
||||
- Small playout buffer chosen by policy, for example 8-20 ms on a wired LAN.
|
||||
- Optional FEC/parity for video chunks where one repair packet beats a resend.
|
||||
- Separate audio policy that favors continuity and bounded drift over perfect
|
||||
packet recovery.
|
||||
|
||||
## OBS Lowering
|
||||
|
||||
The OBS plugin should lower typed media frames into OBS-friendly video/audio.
|
||||
The clean target is direct decode from elementary streams using libavcodec or
|
||||
NVDEC where available, then hand decoded video frames and audio packets to OBS.
|
||||
|
||||
Temporary bridge allowed:
|
||||
|
||||
- Reconstruct an elementary stream from typed video access units.
|
||||
- Feed the local FFmpeg source only as a compatibility decoder.
|
||||
- Keep audio as a separate OBS audio path so audio sync is explicit instead of
|
||||
being hidden inside a damaged MPEG-TS stream.
|
||||
|
||||
The compatibility bridge must not own stream truth. It is a lowering target,
|
||||
not the protocol.
|
||||
|
||||
## Cut Plan
|
||||
|
||||
1. Promote media-frame schemas in Odin/CultLib and add unit tests for
|
||||
encode/decode round trips.
|
||||
2. Teach Muninn activation to emit video access units and audio packets instead
|
||||
of arbitrary MPEG-TS byte chunks.
|
||||
3. Teach CultNet RUDP media receive to reassemble by frame and deadline, with
|
||||
explicit NACK/keyframe feedback.
|
||||
4. Teach the OBS plugin to consume typed media frames and feed OBS through a
|
||||
direct decoder or a narrowly named compatibility elementary-stream bridge.
|
||||
5. Remove the MPEG-TS byte-chunk hot path once the typed receiver is stable.
|
||||
|
||||
## Verification
|
||||
|
||||
The rebuild is not proven by "OBS shows video once." Minimum proof:
|
||||
|
||||
- Raven `serve` remains idle until an explicit capture command arrives.
|
||||
- OBS request activates Raven without manual Raven terminals.
|
||||
- Sender logs and receiver telemetry agree on stream id, session id, frame id,
|
||||
codec, PTS, deadlines, drops, NACKs, and keyframe requests.
|
||||
- A forced packet drop causes bounded damage and recovery, not OBS freeze.
|
||||
- Audio remains present as an OBS audio source and stays within the chosen
|
||||
sync budget.
|
||||
- Restarting OBS does not strand Raven capture or poison the next request with
|
||||
stale command receipts.
|
||||
- Restarting Raven Muninn restores catalog/health without starting capture
|
||||
until requested.
|
||||
262
docs/muninn.md
262
docs/muninn.md
|
|
@ -1,262 +0,0 @@
|
|||
# Muninn
|
||||
|
||||
Muninn is Odin's portable local telemetry Verse assembler.
|
||||
|
||||
It runs on a device body and publishes a typed CultMesh/CultCache surface for
|
||||
what that body can sense or expose locally: screen capture, loopback audio,
|
||||
microphones, cameras, and future sensors.
|
||||
|
||||
## Authority
|
||||
|
||||
- Owner: Muninn owns local telemetry discovery, stream affordance publication,
|
||||
and explicit activation of requested local streams.
|
||||
- Inputs: cheap local probes, operator or Verse activation requests, and local
|
||||
capture tools such as FFmpeg or WASAPI helpers.
|
||||
- Outputs: `muninn.telemetry_surface.v1`, active `muninn.capture_stream.v1`,
|
||||
Quest access records, Move receipt records, and a CultMesh bytes stream
|
||||
carrying live Move evidence frames for Mimir.
|
||||
- Forbidden writers: daemon startup, Idunn keepalive, Mimir ingest, OBS, Odin,
|
||||
Gjallar, and renderer bodies must not start capture by implication.
|
||||
|
||||
## Runtime
|
||||
|
||||
```powershell
|
||||
cargo build -p muninn-daemon
|
||||
muninn serve --store C:\Meta\Odin\state\muninn.telemetry.cc --interval-seconds 15 --idunn-rudp-health $env:IDUNN_RUDP_HEALTH --idunn-daemon starfire-muninn --idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access
|
||||
muninn --health --store C:\Meta\Odin\state\muninn.telemetry.cc
|
||||
```
|
||||
|
||||
`serve` is cheap and idle. It publishes affordances, consumes addressed pending
|
||||
`muninn.move_light_command.v1` records, and keeps the local Verse surface fresh
|
||||
without starting FFmpeg, screen capture, microphone capture, or loopback
|
||||
capture.
|
||||
|
||||
Muninn writes its stream affordance catalog as typed CultCache state inside:
|
||||
|
||||
```text
|
||||
C:\Meta\Odin\state\muninn.telemetry.cc
|
||||
```
|
||||
|
||||
The record is type `muninn.obs_stream_catalog` with schema
|
||||
`muninn.obs_stream_catalog.v1` at key `obs`. Consumers discover the catalog
|
||||
through Odin/CultMesh; Muninn does not publish a parallel OBS RUDP catalog.
|
||||
|
||||
Activation is explicit typed state:
|
||||
|
||||
```powershell
|
||||
muninn request-stream --target-host cultmesh://odin/media/muninn-raven-av --media-transport rudp
|
||||
```
|
||||
|
||||
`target_host` in the legacy command record field is a CultMesh URI, not a host
|
||||
or IP. The activation child resolves `muninn.media.rudp.v1` endpoints from
|
||||
Odin's provider catalog before opening the CultNet RUDP media lane. SRT, OBS
|
||||
target flags, and standalone Raven activation scripts are archived; Mimir,
|
||||
OBS, and other renderers are consumers of Odin/CultMesh discovery, not transport
|
||||
owners.
|
||||
|
||||
## Quest Access And Unity Return Video
|
||||
|
||||
Quest hardware attached to Starfire is a Muninn local telemetry surface, not a
|
||||
Mimir-owned preflight. Enable it by running Muninn on Starfire with ADB probing:
|
||||
|
||||
```powershell
|
||||
muninn serve `
|
||||
--store C:\Meta\Odin\state\muninn.telemetry.cc `
|
||||
--host starfire `
|
||||
--quest-adb `
|
||||
--quest-serial 1WMHHB68PG1515
|
||||
```
|
||||
|
||||
When `adb devices -l` reports the Quest as `device`, Muninn publishes
|
||||
`muninn.quest_access.v1` at `quest-access` and
|
||||
`muninn:<host>:quest-access:<serial>`. The record advertises:
|
||||
|
||||
- `muninn:<host>:quest-input`: Quest buttons/analog/controller input once a
|
||||
Quest/OpenXR witness is running.
|
||||
- `muninn:<host>:quest-poses`: headset and controller poses from that same
|
||||
witness.
|
||||
- `muninn:<host>:quest-warped-video-input`: warp-corrected video frames that
|
||||
Brokkr can route from Starfire Unity editor play mode toward the Quest device.
|
||||
|
||||
ADB authorization proves local USB access only. It does not by itself expose
|
||||
OpenXR poses or accept video frames. A Quest/OpenXR witness still owns headset
|
||||
runtime sampling, while Brokkr owns the Unity editor adapter that sends
|
||||
warp-corrected play-mode frames to Muninn's advertised Quest video input.
|
||||
|
||||
Read the current record with:
|
||||
|
||||
```powershell
|
||||
muninn quest-access-status --store C:\Meta\Odin\state\muninn.telemetry.cc
|
||||
```
|
||||
|
||||
For Starfire's local Quest-attached daemon, Idunn supervises the
|
||||
`starfire-muninn` target through:
|
||||
|
||||
```powershell
|
||||
E:\Projects\Odin\scripts\restart-starfire-muninn.cmd
|
||||
E:\Projects\Odin\scripts\health-starfire-muninn.cmd
|
||||
```
|
||||
|
||||
The restart script launches Muninn hidden with `--host starfire --quest-adb`,
|
||||
`--idunn-rudp-health` from explicit `-IdunnRudpHealth` or
|
||||
`IDUNN_RUDP_HEALTH`, `--idunn-daemon starfire-muninn`, and
|
||||
`--idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access`.
|
||||
If the CultCache store at `C:\Meta\Odin\state\starfire.muninn.telemetry.cc`
|
||||
fails MessagePack decode on boot, the restart path archives the corrupt file,
|
||||
clears the stale `.lock`, and relaunches the daemon instead of leaving the lane
|
||||
dead.
|
||||
|
||||
The deployed loopback helper must accept Muninn's command contract:
|
||||
|
||||
```powershell
|
||||
wasapi-loopback-capture.ps1 -Output stdout -Device Realtek -SampleRate 48000 -Channels 2
|
||||
```
|
||||
|
||||
`stdout` is an alias for binary standard output, and `Device` is the requested
|
||||
render-device hint. Current helper builds may ignore the hint and use the
|
||||
default render endpoint, but they must accept the argument so Muninn's generated
|
||||
mux command remains executable.
|
||||
|
||||
## Move Marker Candidates
|
||||
|
||||
`crates/muninn-move-tracker` is Muninn's native/Rust PS Move optical candidate
|
||||
extractor. It owns dispatch planning, FFI, configuration validation, a CPU
|
||||
mirror, and the HLSL 16px-tile luma reduction shader. It emits marker
|
||||
candidates only: weighted centroid, radius, area, peak/mean luma, and score for
|
||||
one camera frame.
|
||||
|
||||
Muninn owns publishing those candidates as `muninn.move_marker_candidate.v1`.
|
||||
Muninn also publishes USB controller facts as
|
||||
`muninn.move_controller_state.v1`: accelerometer, gyro, magnetometer, button,
|
||||
trigger, battery, sequence, and source timestamp. Mimir is the consumer of both
|
||||
sensor streams. Odin may discover and project the schemas, but Odin does not
|
||||
own raw capture, candidate extraction, calibration, triangulation, IMU fusion,
|
||||
prediction, or final 6DoF pose. Muninn does not synthesize wand pose; it
|
||||
reports what the local body saw and read from USB.
|
||||
|
||||
The hot tracking path is a CultMesh stream, not CultCache polling. When
|
||||
`serve` has one or more `--move-state` sources, it declares
|
||||
`muninn:<host>:move-evidence` in Verse `mimir-live` and publishes
|
||||
MessagePack `mimir.muninn_move_evidence_stream_frame.v1` bytes through a
|
||||
shared-memory frame ring. The frame contains any marker candidates available
|
||||
from local optical extraction plus the controller states read from USB. The
|
||||
`muninn.move_marker_candidate.v1` and `muninn.move_controller_state.v1` records
|
||||
remain receipts/debug state in the `.cc` store; Mimir drinks the stream and
|
||||
owns association, calibration, fusion, prediction, and final pose.
|
||||
|
||||
On Linux hosts, enable the controller-state feed by passing one or more Move
|
||||
joystick sources to `serve`:
|
||||
|
||||
```bash
|
||||
muninn serve \
|
||||
--store ~/.local/state/gamecult/muninn/muninn.telemetry.cc \
|
||||
--host nightwing \
|
||||
--move-state move-usb=/dev/input/by-id/usb-Sony_Computer_Entertainment_Motion_Controller-joystick
|
||||
```
|
||||
|
||||
The published values are raw Linux joystick/HID counts. Mimir owns calibration,
|
||||
axis interpretation, unit conversion, fusion, prediction, and resolved pose
|
||||
publication. Hidraw remains the local output path for LED reports.
|
||||
Use `--move-evidence-stream <stream-id>` or `--move-evidence-verse <verse-id>`
|
||||
only when the default `muninn:<host>:move-evidence` / `mimir-live` address is
|
||||
not the desired Mimir-facing stream identity.
|
||||
|
||||
## Move Light Commands
|
||||
|
||||
Muninn is also the local output owner for USB-attached PS Moves. When Mimir
|
||||
wants structured light pulses for calibration or tracking, it publishes a typed
|
||||
`muninn.move_light_command.v1` command over CultNet/CultMesh to the Muninn
|
||||
daemon on the host that owns the Move. `serve` consumes `pending` commands
|
||||
whose `host_id` matches the local Muninn host, writes PS Move HID report `0x06`
|
||||
to the command's `hidraw_path`, and updates the same command record to
|
||||
`running`, `completed`, or `failed`.
|
||||
|
||||
For operator smoke and bring-up, `request-move-light` writes that typed command
|
||||
into the local Muninn store without touching HID directly:
|
||||
|
||||
```bash
|
||||
muninn request-move-light \
|
||||
--store ~/.local/state/gamecult/muninn/muninn.telemetry.cc \
|
||||
--host nightwing \
|
||||
--move move-usb \
|
||||
--hidraw /dev/hidraw1 \
|
||||
--color 35ff6c \
|
||||
--duration-ms 0 \
|
||||
--repeat-count 1
|
||||
|
||||
muninn move-light-status \
|
||||
--store ~/.local/state/gamecult/muninn/muninn.telemetry.cc \
|
||||
--host nightwing
|
||||
```
|
||||
|
||||
Idunn keeps the Muninn daemon alive. Idunn does not learn a Move-specific
|
||||
watcher, and Mimir does not write HID directly except through temporary smoke
|
||||
scripts used to prove hardware behavior before a Muninn daemon is available.
|
||||
When `serve` is launched with `--idunn-rudp-health`, `--idunn-daemon`, and
|
||||
`--idunn-health-contract`, the long-running Muninn body publishes
|
||||
`idunn.daemon_health` directly to Idunn over `cultnet.transport.rudp.v0` on its
|
||||
normal cadence. `--health` keeps the same publication path for manual proof and
|
||||
compatibility probes, but the live owner is the daemon's `serve` process.
|
||||
Quest ADB probing is a telemetry input, not daemon liveness. If `adb` is
|
||||
missing or the Quest is unavailable, Muninn publishes `muninn.quest_access` as
|
||||
`unavailable` and keeps serving the local telemetry surface.
|
||||
|
||||
## Host Deployments
|
||||
|
||||
Raven runs Muninn from `C:\Meta\Odin\Muninn`. `scripts/restart-muninn.ps1`
|
||||
recreates only the `GameCult-Muninn` scheduled task. It also unregisters the
|
||||
obsolete `GameCult-Muninn-Activate` and `GameCult-Muninn-VideoProof` tasks if
|
||||
they are present. The serve launcher starts `muninn.exe` with
|
||||
`-WindowStyle Hidden`, requires `--idunn-rudp-health` from explicit
|
||||
`-IdunnRudpHealth` or `IDUNN_RUDP_HEALTH`, passes `--idunn-daemon muninn`, and
|
||||
`--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-health`, and
|
||||
requires `-MediaTargetUri` / `MUNINN_MEDIA_TARGET_URI` to be a `cultmesh://`
|
||||
URI resolved through Odin at activation time. It
|
||||
redirects logs under `C:\Meta\Odin\logs\muninn`.
|
||||
Raven is an operator-consented host: Muninn operations on Raven must be
|
||||
background-only and must not create visible terminal windows. `.cmd` files may
|
||||
exist only as manual compatibility entrypoints that call the same hidden VBS
|
||||
launchers; neither Task Scheduler nor the hidden VBS layer may route through a
|
||||
`cmdPath` trampoline on Raven.
|
||||
Health must fail if the obsolete activation or video-proof tasks still exist on
|
||||
Raven. If Raven is unreachable, the repo is prepared but the live scheduler is
|
||||
not clean.
|
||||
|
||||
Nightwing Muninn is kept alive by the single Idunn supervisor through the
|
||||
`nightwing-muninn` daemon target. Idunn learns that target through Odin's typed
|
||||
daemon surface and invokes `scripts/health-nightwing-muninn.ps1` and
|
||||
`scripts/restart-nightwing-muninn.ps1`; those scripts are health/restart
|
||||
actuators only, not lifecycle owners. The binary is installed at
|
||||
`/home/metacrat/.local/bin/muninn`, the store lives at
|
||||
`/home/metacrat/.local/state/gamecult/muninn/muninn.telemetry.cc`, and the
|
||||
restart actuator launches `serve --host nightwing --interval-seconds 15` with
|
||||
`--move-state move-usb=/dev/input/by-id/usb-Sony_Computer_Entertainment_Motion_Controller-joystick`,
|
||||
`--idunn-rudp-health` supplied by explicit `-IdunnRudpHealth` or
|
||||
`IDUNN_RUDP_HEALTH`,
|
||||
`--idunn-daemon nightwing-muninn`,
|
||||
`--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-and-move-hid`,
|
||||
PID, and logs under
|
||||
`/home/metacrat/.local/state/gamecult/muninn`.
|
||||
With that Move state source attached, `serve` also publishes the
|
||||
`muninn:nightwing:move-evidence` CultMesh stream frame body that Mimir's native
|
||||
Move evidence reservoir consumes.
|
||||
Nightwing source discovery must emit one Move source per controller id. The USB
|
||||
pairing collection and Bluetooth joystick can expose the same controller as
|
||||
separate `/dev/input/js*` paths; `nightwing-move-state-sources.sh` prefers the
|
||||
Bluetooth `HID_ID=0005:0000054C:000003D5` path so Idunn health does not demand
|
||||
fresh records from two faces of the same controller. The Nightwing health
|
||||
actuator requires the same configured Idunn RUDP endpoint, but that command is
|
||||
fallback proof only; the live keepalive contract is now published by the
|
||||
long-running Nightwing `serve` process.
|
||||
|
||||
Each private PSMoveAPI Eye worker owns optical observation admission before the
|
||||
parent aggregates evidence. Positions older than 50 ms, blobs below 2 px,
|
||||
out-of-frame coordinates, implausible radius jumps, and frame-to-frame
|
||||
teleports are rejected locally. Typed `muninn.move_tracker_health.v1` records
|
||||
publish rejection counts by stale/radius/bounds/continuity reason.
|
||||
|
||||
PSMoveAPI's position age is freshness, not optical confidence. The aggregate
|
||||
marker candidate therefore carries an explicit uncalibrated score of `0.5`
|
||||
until the observer exposes a real fit-quality measure. Consumers must not treat
|
||||
the thresholded color-blob radius as a calibrated physical sphere silhouette;
|
||||
per-Eye radius response belongs to Mimir's calibration evidence.
|
||||
Loading…
Reference in a new issue