HZMediaP
Specification

{
  "hzmp":    "1.0",        // protocol version — must be "1.0"
  "msgid":   "<uuid-v4>",  // unique message ID
  "type":    "STREAM_INIT",// message type constant
  "ts":      1712000000000,// sender Unix timestamp (ms)
  "ref":     null,          // msgid of the message being replied to, or null
  "payload": { /* type-specific */ }
}

const ws = new WebSocket('wss://stream.covelabs.io/ws');
let sessionNonce, accessToken;

function send(type, payload, ref = null) {
  ws.send(JSON.stringify({
    hzmp:  '1.0',
    msgid: crypto.randomUUID(),
    type, ts: Date.now(), ref, payload,
  }));
}

ws.onopen = () => {
  send('HANDSHAKE', {
    client_name:    'my-app',
    client_version: '1.0.0',
    platform:       'web',
    capabilities:   ['hls'],
  });
};

ws.onmessage = async ({ data }) => {
  const msg = JSON.parse(data);

  switch (msg.type) {
    case 'HANDSHAKE_ACK': {
      sessionNonce = msg.payload.session_nonce;
      const idToken = await getGoogleIdToken();
      send('AUTH', {
        strategy:  'firebase',
        id_token:  idToken,
        nonce:     sessionNonce,
      });
      break;
    }
    case 'AUTH_OK': {
      accessToken = msg.payload.access_token;
      // Session ready — send a search
      send('SEARCH', { query: 'late night jazz', mode: 'hybrid' });
      // Start heartbeat loop
      setInterval(() => send('HEARTBEAT', {}),
        msg.payload.heartbeat_interval_ms);
      break;
    }
    case 'SEARCH_RESULT': {
      const first = msg.payload.items[0];
      if (first) send('STREAM_INIT', {
        content_id: first.content_id,
        resume:     true,
      });
      break;
    }
    case 'STREAM_READY': {
      // Pass hls_master_url to your player (e.g. hls.js)
      player.loadSource(msg.payload.hls_master_url);
      break;
    }
    case 'ERROR': {
      console.error(msg.payload.code, msg.payload.message);
      if (msg.payload.retryable) /* retry with backoff */;
      break;
    }
  }
};

{
  "hzmp": "1.0", "msgid": "…", "type": "SEARCH", "ts": …, "ref": null,
  "payload": {
    "query":         "late night jazz",
    "mode":          "hybrid",
    "vector_weight": 0.7,
    "filters": {
      "content_type":  ["audio"],
      "duration_min_s": 120,
      "tags":          ["instrumental"]
    },
    "limit": 20,
    "offset": 0
  }
}

// Create
{ "type": "PLAYLIST_REQUEST", "payload": {
  "action": "create", "name": "Evening Wind-Down"
} }

// Server responds with new playlist_id in PLAYLIST_RESPONSE

// Add item
{ "type": "PLAYLIST_REQUEST", "payload": {
  "action":      "add_item",
  "playlist_id": "pl_abc123",
  "content_id":  "ct_xyz789"
} }

{ "type": "HEARTBEAT", "payload": { "session_id": null } }

// Server responds:
{ "type": "HEARTBEAT_ACK", "payload": { "server_ts": 1712000030000 } }