P024 Listener Web Shell

Live queue, visible reasons, no fake player.

This listener web surface is the first truthful shell for the current platform. It is built around live queue planning, feedback, explainability, and playback handoff boundaries that already exist in recommendation-api and playback-api.

AI stream mode reranks continuously Rights-first before queue or playback Explainability with causal factors

Read-only live queue probe

This is the first live listener wiring. It sends an inline session payload to the same-origin listener edge at POST /api/session/queue, preserves the planner contract used by POST /v1/session/queue, uses the same deterministic probe pack as listener-session validation, and avoids fake playback or feedback mutations.

Probe controls

Run a truthful queue contract probe

Current public edge truth: `api.zenosound.com` currently serves the metadata bootstrap surface, not recommendation-api. The public listener shell now uses a same-origin listener edge instead of pointing the browser at that bootstrap host.

The probe pack is contract-grade and seeded with one blocked artist plus energetic boost and calm suppress tag controls so queue explainability and rights filtering stay visible.

Request summary
Waiting for live queue probe

No live request sent yet. Run the probe to call the same-origin listener queue edge.

Queued tracks

Queued tracks will appear here with explainability and applied constraints.

Filtered and metadata

Filtered candidates will appear here with explicit reasons.

Metadata and policy metrics will appear here after the first successful probe.

Listener interaction rails

These are the product-facing states already backed by current services. The shell stays static-first for now, but the copy and structure map directly to live routes.

Session intent

Capture territory, explicit-policy, blocked artists, blocked assets, and manual tag controls before ranking.

  • Boost, suppress, or block tags at runtime.
  • Keep session constraints explicit instead of hidden in client state.
  • Feed the same policy inputs used by downstream playback checks.

Behavior feedback

Turn listener actions into deterministic feedback state that can alter the next queue outcome within seconds.

  • Save, replay, finish-rate, skip, dislike, artist block/unblock.
  • Snapshot export/import exists for replay and audit.
  • No opaque personalization loop is implied here.

Playback transition

Queue planning alone is not enough. The shell also points clearly to startup, authorize, and CDN handoff so the listener understands when rights gates re-run.

  • Startup and handoff reject empty authoritative ledgers.
  • Authorize stays deterministic and rights-first.
  • Blocked decisions remain visible instead of being silently suppressed.

Current platform truth

The listener shell should surface these product promises because they already match the backend contract and validation suite.

Queue behavior

AI stream mode is live and event-driven

  • Queue planning horizon stays short instead of prebuilding an endless station.
  • Session events can trigger deterministic replans.
  • Static playlists can coexist with the AI stream rather than replacing it.
Explainability

Every queued track needs visible reasons

  • Top matched tags.
  • Similarity rationale.
  • Applied constraints such as rights, explicit policy, and artist caps.
Curation policy

Hard filters are not optional

  • Territory rights, availability windows, explicit settings, blocks, dislikes.
  • Diversity and novelty guards stay visible as policy, not magic.
  • Promotion is allowed only when it remains labeled and policy-bounded.

Listener-facing API surfaces

These routes are the source of truth for the shell. This page should help product and design work stay aligned to the current service reality.

POST /v1/session/intent

Set live session intent controls and constraints before queue planning.

POST /v1/session/feedback

Apply save, replay, skip, dislike, and manual controls into deterministic behavior state.

POST /v1/session/queue

Resolve current session intent and behavior into a policy-aware queue plan.

POST /v1/playback/startup

Build startup and buffer tracks while revalidating rights on the playback path.

POST /v1/playback/authorize

Produce deterministic allow or deny decisions with reason codes and applied constraints.

POST /v1/playback/handoff

Move from planned queue into listener-ready streaming or explicit blocked fallback state.

This shell now includes a read-only live queue probe through inline session payloads and a same-origin listener edge. The next step is replacing the deterministic probe pack with real candidate supply, still without faking playback or hiding rights and policy gates.