MiladRTX--Glint/docs/API.md

Glint payload HTTP API (port 7231)

The payload on the PS5 serves the console's H.264 encoder output, its audio and a set of controls over HTTP. The desktop app and the browser dashboard are both clients of this API.

Transport: plain HTTP/1.1 over TCP. Every response sets Connection: close and Cache-Control: no-store (where applicable). The request line is parsed as %11s %255s; only the method and path are used. A request must be complete within 5 seconds (server-side receive timeout 1 s, header deadline 5 s, 4095-byte limit).

Routes

Method	Path	Response
GET	/	text/html; charset=utf-8, the dashboard page
GET	/banner.png	image/png, the banner image
GET	/config.json	stream configuration
GET	/status.json	live statistics
GET	/frames	framed H.264 stream (endless)
GET	/audio	framed PCM stream (endless)
GET	/rtp/video?port=N	RTP/AVC stream to the caller's IP on UDP port N
GET	/recordings	JSON array of recordings
GET	/recordings/<name>	recording download
POST	/record/start	arm recording on the next IDR
POST	/record/stop	close and finalize the recording
POST	/video/keyframe	request an IDR from the encoder
POST	/capture/profile?height=H	change capture height
POST	/capture/restart	restart the capture session
POST	/stop	stop streaming and release capture

Unknown routes return HTTP 200 with the body Unavailable route (text/plain).

Video framing (/frames)

Each frame is:

offset  size  field
0       4     payload length, big-endian (max 2,097,152)
4       4     presentation timestamp, big-endian, 90 kHz units
8       N     Annex-B access unit (00 00 00 01 / 00 00 01 start codes)

The first frame after a connection is a keyframe (the server requests one on connect). After that keyframes come from the encoder's own schedule, after a skip (below), or on POST /video/keyframe; the server does not force periodic ones, because each large IDR is a latency spike on a slow link (Wi-Fi). The PC recorder requests one every 2 s while it records. Timestamps are 32-bit and wrap; the dashboard unwraps the delta.

Ring: 64 slots. When a viewer falls more than 6 frames behind the server drops to the newest available IDR and requests another keyframe. Streaming clients are capped at 8; the 9th gets HTTP/1.1 503 Busy with an empty body.

Audio framing (/audio)

offset  size  field
0       4     payload length, big-endian (max 65,536)
4       4     timestamp, big-endian (console clock)
8       N     PCM samples

Codecs advertised in config.json:

• pcm_f32le — 32-bit float, interleaved
• pcm_s16le — signed 16-bit
• pcm_s32le — signed 32-bit

Default console stream: pcm_f32le, 2 channels, 48000 Hz. The capture layer emits one packet per audio frame batch, typically 8192 bytes (1024 stereo float samples).

config.json

{
  "platform": "PS5",
  "width": 1920,
  "height": 1080,
  "fps": 60,
  "codec": "avc1.4d4032",
  "sps": "674d403291a01e0089f97016a020202800001f48000ea6044d0f1f50",
  "pps": "68ee3c80",
  "audio": {
    "codec": "pcm_f32le",
    "channels": 2,
    "rate": 48000,
    "bits": 32
  },
  "resolutions": [1080],
  "requested_height": 1080,
  "profile_changing": false,
  "profile_error": false
}

• codec is avc1.%02x%02x%02x from sps[1..3] (profile, constraints, level).
• sps/pps are lowercase hex without start codes.
• audio is null when no audio channel is open.
• Glint captures 1080p60 only (capture feature 12). On current firmware 1440p OpenVideo returns 0x81950008 (profile unsupported), and a failed 1440p attempt can leave the encoder in a state where Start returns 0x80c78000, so the payload opens 1080p directly without probing. See docs/CAPTURE-INTERNALS.md for the full error-code table.

status.json

{
  "version": "1.5",
  "backend": "h264",
  "width": 1920,
  "height": 1080,
  "frames": 648,
  "bytes": 1354059,
  "fps": 60.3,
  "kbps": 1008.8,
  "clients": 1,
  "viewers": 1,
  "bitrate": 20000000,
  "recording": false,
  "recording_name": "",
  "recording_frames": 0,
  "recording_bytes": 0,
  "recording_seconds": 0.0,
  "recording_error": false,
  "audio_chunks": 508,
  "audio_bytes": 4161536,
  "audio_kbps": 3108.5,
  "audio_codec": "pcm_f32le"
}

fps and kbps are frames and bytes since the payload started divided by the time since the server last (re)started, so they overcount after an encoder reopen. The app shows its own rate over the last 2 s instead. clients counts every open request socket (including status polling). viewers is how many people are watching: 1 while the current viewer has a stream open, else 0 (see One viewer at a time).

Recording

• Directory: /data/glint/recordings (created on demand).
• Trigger: the first IDR after POST /record/start.
• File name: glint-<unix-time>-<frame-count>.h264.
• Contents: [BE u32 len][SPS] [BE u32 len][PPS] followed by Annex-B access units. A new SPS/PPS pair is written after a discontinuity.
• POST /record/stop finalizes the file and fills recording_name, recording_frames, recording_bytes, recording_seconds.
• A recording error sets recording_error and closes the file.
• Listing entries: {"name":"...","bytes":123}.
• Download names are restricted to [A-Za-z0-9.-], must end in .h264, must not start with ., must not contain .., and are at most 96 chars.

Profile changes

POST /capture/profile?height=H accepts only 1080 (anything else is 400).

• 400 Unsupported resolution — bad height or trailing characters.
• 409 Stop recording before changing resolution.
• 409 A resolution change is already in progress.
• 200 Resolution unchanged — same as current.
• 200 Resolution change requested — capture loop reopens avcap2 and bumps the stream generation, which disconnects current viewers.

Response body shape: {"message":"..."} over HTTP/1.1 <code> Profile.

RTP

GET /rtp/video?port=N (accepted range 1024–65535):

1. Sends HTTP/1.1 200 OK ... RTP\n.
2. Opens a UDP socket to the caller's address with the requested port.
3. Packetizes Annex-B NAL units as RTP/AVC (payload type 96, 90 kHz clock).
4. SPS and PPS are prepended to every keyframe, each with a 4-byte start code.
5. NALs larger than 1400 bytes use FU-A fragmentation; the marker bit is set on the last packet of each access unit.

Limits and concurrency

Resource	Value
Client slots	16
Streaming slots (/frames, /audio, /rtp)	8
Video ring	64 entries
Audio ring	256 entries
Request header	4095 bytes
Header deadline	5 s
Send timeout	5 s
Receive timeout	1 s
Max video frame	2 MiB
Max audio packet	64 KiB

One viewer at a time

/frames, /audio and /rtp/video belong to one viewer at a time. A viewer is named by ?viewer=<id> (letters, digits, -, _; the dashboard makes a new one per page) or, without it, by the client's IP address (the desktop app).

• A different viewer connecting takes over: every stream of the current viewer ends.
• A viewer that was pushed out is refused with HTTP 409 while the one that pushed it is still watching (or reconnecting within 5 s), so two clients that reconnect on their own can't take turns kicking each other.
• &take=1 takes over anyway (the dashboard's Watch here button).
• Once the current viewer has been gone for 5 s, anyone can connect again.

Bitrate

The encoder runs at 20 Mbit/s (bitrate in status.json; a bitrate=N start argument changes it). Measured in a busy game over Wi-Fi, 20 Mbit/s hitched about half as often as 30, and 40 and 60 more still; a calm home screen needs far less.

It is set once, before Start, and can't change while Glint runs (tested on a PS5, 13.60):

• SetVideoBitrate on a running session returns ok, but every ReadVideo after it fails with 0x80c78000 and the encoder stays locked until a restart.
• Closing the session cleanly (Stop, Close, arbitrator cleared) and opening a new one gets through OpenVideo and SetVideoBitrate, then Start is refused with 0x80c78000. The encoder takes one capture session per boot.
• Every frame is a reference frame (nal_ref_idc 2), so a cap after the encoder can't drop frames without breaking the picture.