Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

10.6 KB
Raw Blame

Media Status

src/client/ui/media-status.ts owns the shared visual projection, demonstrated by /__status-preview. It is not a routing or quality controller. The existing presentation reducer continues to own playback facts; roster and quality evidence retain their own authority. Overlay, indicators, notices and title are consumers, not truth sources.

Frontend controls, names and details share Tooltip, following the visual language. Its native Popover top layer escapes scrolling containers, with viewport-relative placement. Hover, keyboard focus and touch hold share one visibility owner; Escape dismisses even a mouse-only hint. /__tooltip-preview shows the catalogue. Playback actions and their local audio ownership are defined in presentation lifecycle; /__playback-preview exercises the actual control bar with generated local media.

Status Meaning

Keep three questions separate: is the media path available, is this picture playing, and is this particular stream limited? An available path does not prove excellent quality. One weak child does not make its parent's received picture or a healthy sibling unhealthy.

The shared visual language owns colours, cast, shapes, panel accents and motion. This document owns the evidence and scope that select those meanings. Current StatusDescriptor tone and progress take precedence over a reused comic's default; text and pure-visual tooltips retain that context.

Projection Rules

  • Overlay: appears when there is no usable picture, an intentional Host pause, or a required user action. Ordinary quality warnings never cover playback. Initial connection guidance is not an error even though it occupies the stage.
  • Television: one media-status icon sits inside the lower television frame (lr-tv-chin). Every mode explains it with the same comic tooltip; text modes add the specific localized status beneath the scene. Both reuse Tooltip for hover, keyboard focus, touch hold and viewport placement; no native title competes with the custom status hint. There is no permanent text bubble, additional round lamp, or repeated control-menu caption. Room/session termination refines this same indicator before and during sharing; it must not become an operation pill merely because no source is active. Keep its reason available to assistive technology without moving focus. The Host television describes its local source, not an arbitrary outbound child. A confirmed limitation may colour the relevant icon amber while the page title still says watching. A Host failure may open a troubleshooting dialog from this same icon. Keep the existing hover explanation; the dialog owns actionable help, not a second banner or an interactive tooltip. Preserve the observed operation and failure boundary (timeout, disconnect, rejection); an unspecified App rejection does not establish a driver or network cause. Copy only bounded diagnostic context, never raw exceptions, source names or invitation URLs. Recording remains an explicit opt-in through the shared diagnostic control. Troubleshooting follows the known failure boundary: unknown/session/settings failures must not default to capture advice, and retiring a share must retain a known App control or media-connection failure instead of replacing it with a generic stop notice.
  • Host couch: each Viewer has one round lamp. Grey means present without a media connection, blue means connecting, green means a committed picture or voice route, and amber means a recent picture receive freeze. participantConnection projects the server's confirmed picture/voice facts for both the lamp and topology; microphone capture and sharing controls do not own connectivity. The Host's own pawn has no duplicate lamp. deriveParticipantStatus supplies both the couch and Host overview; neither stores another copy of the status.
  • Viewer couch: pawns have no round lamps. While awaiting media readiness a pawn's body breathes gently; it becomes still when ready. This expresses the same roster fact without claiming to know other Viewers' quality.
  • Integrated pawn accessories describe participation: headphones mean voice membership, worn on the head while listening and around the neck when listening is paused. The microphone boom extends when input is on and folds up when muted. A mouse on the body identifies an approved remote controller regardless of device. Shared glyphs use the cast's ink and existing pawn motion. Their facts come from voice membership/publication, local listening and native grants; leaving an activity removes its marker. Pausing listening does not mute the microphone or change forwarding or routes. The route lamp remains separate; these accessories do not assert connection health or speaking activity.
  • Header: the page's connection to the room server. Its control-link comics show a Browser and server, not a failed video path. A media-route failure can coexist with a healthy server connection, and vice versa.
  • Connection notice: signaling recovery may coexist with healthy media. It cannot convert proved playback into waiting or hide media recovery. The presentation stage owns the primary media status; a coexisting notice never selects that status or asserts another connection's health.
  • Notices: necessary coexisting issues and operation feedback use the existing pills below the stage; they are not another primary media status. Ordinary notices stay outside the picture and are hidden with surrounding controls in theatre mode. Operation results have a dismiss button; condition-based notices disappear when their owning condition clears. Signal recovery must not leave a stale operation warning after reconnection. Remote-input and voice feedback stays in its own controls or tool panel. Raw PeerConnection errors remain diagnostic observations, not persistent red warnings after media recovers. The control menu does not repeat the television status or aggregate the first weak outbound edge into a global quality warning. The operation supplies its outcome tone and matching scene together. Neither the presence of an illustration nor a default checkmark proves success; partial application retains a limitation instead of claiming completion.
  • Source sound: every capture source with confirmed absent source audio keeps the same neutral notice and detail, including camera capture. This describes the captured input, not a failure or the mixed output's sound. The microphone control owns voice state separately; do not hide facts by source category or infer missing audio while capture details are unknown.
  • Host absence: without a proved current picture, a stopped/unknown Host means waiting for sharing, and an offline Host means waiting for return. A failed route does not override those facts. Retain route evidence so reconnection alone cannot claim media recovery; independent playback/server errors retain their meaning. An authenticated snapshot with an absent Host does not identify why the Host is absent: use neutral waiting. Only the explicit sharing-stop event establishes an intentional stop; do not reconstruct it from a retained share generation or remembered messages.
  • Topology: unready edges use the blue pending treatment. Readiness alone cannot distinguish initial connection from recovery, so this view does not invent a warning. Confirmed interruption remains owned by the status projection.
  • Title: keeps the primary activity, with a compact warning for an applicable problem. Losing focus alone never means waiting for media.
  • Recovery: every projection is recomputed from current facts. A warning requires current evidence; an expired or mismatched sample becomes unknown, not healthy or disconnected. A ready participant can therefore return to a green readiness lamp without claiming that its quality has recovered. No warning latch or additional timer is needed.

Evidence And Integration Boundary

Use WebRTC connectionState for transport explanation, not first-frame proof. disconnected may recover; failed is terminal for that connection. Closing a retired connection is not an error in the replacement connection. qualityLimitationReason describes an outbound encoder. A relay's sender warning must never become a warning about its own inbound picture. Low FPS, resolution or bitrate alone does not prove poor quality; a static screen or a small source can legitimately need little data. Do not introduce UI thresholds or a new quality score.

Current roster messages expose committed mediaReady to both roles, not a complete remote quality/failure state. Missing readiness means waiting or recovery, not confirmed disconnection; departed participants leave the roster. Viewer receive evidence is shared with its parent and the Host, not with every other Viewer. No additional remote-quality broadcast is needed.

The Host's amber participant lamp requires an active share, committed readiness, fresh receive evidence for the current upstream, and a positive freezeCountDelta or freezeDurationMsDelta. The existing evidence-expiry path clears stale warnings. Hidden, paused and other diagnostic-only windows provide no freeze proof; low FPS, resolution or bitrate is not a substitute.

All *Delta metrics describe one observation window and never inherit an older non-null value. Non-window fields retain the existing details-display cache. Participant status reads the current evidence directly; it adds no stored status, timer, threshold or score. Detailed sender/receiver metrics remain available in connection details and Debug with their original scope.

Previews render the production projection and metric components with explicit sample inputs. They do not add quality facts absent from the real workflow.

References

We reuse these distinctions and the existing Piik owners, not a new SDK, scoring algorithm or transport policy.