@tx5dr/contracts 1.4.0 → 1.6.0

package/src/schema/realtime.schema.ts

@@ -3,15 +3,158 @@ import { z } from 'zod';
 export const RealtimeScopeSchema = z.enum(['radio', 'openwebrx-preview']);
 export type RealtimeScope = z.infer<typeof RealtimeScopeSchema>;
 
-export const RealtimeParticipantKindSchema = z.enum(['listener', 'publisher', 'bridge']);
-export type RealtimeParticipantKind = z.infer<typeof RealtimeParticipantKindSchema>;
-
-export const RealtimeTransportKindSchema = z.enum(['livekit', 'ws-compat']);
+export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat']);
 export type RealtimeTransportKind = z.infer<typeof RealtimeTransportKindSchema>;
 
 export const RealtimeSessionDirectionSchema = z.enum(['recv', 'send']);
 export type RealtimeSessionDirection = z.infer<typeof RealtimeSessionDirectionSchema>;
 
+export const RealtimeAudioCodecSchema = z.enum(['opus', 'pcm-s16le']);
+export type RealtimeAudioCodec = z.infer<typeof RealtimeAudioCodecSchema>;
+
+export const RealtimeAudioCodecPreferenceSchema = z.enum(['auto', 'opus', 'pcm']);
+export type RealtimeAudioCodecPreference = z.infer<typeof RealtimeAudioCodecPreferenceSchema>;
+
+export const DEFAULT_REALTIME_AUDIO_CODEC_PREFERENCE: RealtimeAudioCodecPreference = 'auto';
+
+export const RealtimeAudioCodecCapabilitiesSchema = z.object({
+  opus: z.object({
+    encode: z.boolean().optional(),
+    decode: z.boolean().optional(),
+    sampleRates: z.array(z.number().int().positive()).optional(),
+    encodeSampleRates: z.array(z.number().int().positive()).optional(),
+    decodeSampleRates: z.array(z.number().int().positive()).optional(),
+  }).optional(),
+  pcmS16le: z.boolean().optional(),
+}).optional();
+export type RealtimeAudioCodecCapabilities = z.infer<typeof RealtimeAudioCodecCapabilitiesSchema>;
+
+export const ResolvedRealtimeAudioCodecPolicySchema = z.object({
+  preference: RealtimeAudioCodecPreferenceSchema,
+  resolvedCodec: RealtimeAudioCodecSchema,
+  fallbackReason: z.enum([
+    'not-needed',
+    'client-forced-pcm',
+    'client-opus-unavailable',
+    'server-opus-unavailable',
+    'scope-not-supported',
+  ]).nullable(),
+  codecSampleRate: z.number().int().positive().nullable(),
+  bitrateBps: z.number().int().positive().nullable(),
+  frameDurationMs: z.number().int().positive().nullable(),
+});
+export type ResolvedRealtimeAudioCodecPolicy = z.infer<typeof ResolvedRealtimeAudioCodecPolicySchema>;
+
+export const VoiceTxBufferProfileSchema = z.enum(['auto', 'custom']);
+export type VoiceTxBufferProfile = z.infer<typeof VoiceTxBufferProfileSchema>;
+
+export const VoiceTxCustomTargetBufferMsSchema = z.preprocess((value) => {
+  if (value === '' || value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : value;
+  }
+  return value;
+}, z.number().int().min(40).max(500).optional());
+
+export const VoiceTxBufferPreferenceSchema = z.preprocess((value) => {
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+  const preference = value as { profile?: unknown };
+  if (
+    preference.profile === 'low-latency'
+    || preference.profile === 'balanced'
+    || preference.profile === 'stable'
+  ) {
+    return { ...preference, profile: 'auto' };
+  }
+  return value;
+}, z.object({
+  profile: VoiceTxBufferProfileSchema.default('auto'),
+  customTargetBufferMs: VoiceTxCustomTargetBufferMsSchema,
+})).superRefine((value, ctx) => {
+  if (value.profile === 'custom' && typeof value.customTargetBufferMs !== 'number') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['customTargetBufferMs'],
+      message: 'Custom TX buffer target is required for custom profile',
+    });
+  }
+});
+export type VoiceTxBufferPreference = z.infer<typeof VoiceTxBufferPreferenceSchema>;
+
+export const ResolvedVoiceTxBufferPolicySchema = z.object({
+  profile: VoiceTxBufferProfileSchema,
+  targetMs: z.number().int().min(1),
+  minMs: z.number().int().min(1),
+  maxMs: z.number().int().min(1),
+  headroomMs: z.number().int().min(1),
+  staleFrameMs: z.number().int().min(1),
+  uplinkMaxBufferedAudioMs: z.number().int().min(1),
+  uplinkDegradedBufferedAudioMs: z.number().int().min(1),
+});
+export type ResolvedVoiceTxBufferPolicy = z.infer<typeof ResolvedVoiceTxBufferPolicySchema>;
+
+export const DEFAULT_VOICE_TX_BUFFER_PROFILE: VoiceTxBufferProfile = 'auto';
+
+const VOICE_TX_BUFFER_PRESETS: Record<Exclude<VoiceTxBufferProfile, 'custom'>, ResolvedVoiceTxBufferPolicy> = {
+  auto: {
+    profile: 'auto',
+    targetMs: 80,
+    minMs: 60,
+    maxMs: 400,
+    headroomMs: 40,
+    staleFrameMs: 650,
+    uplinkMaxBufferedAudioMs: 180,
+    uplinkDegradedBufferedAudioMs: 360,
+  },
+};
+
+function clampVoiceTxBufferValue(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+export function resolveVoiceTxBufferPolicy(
+  preference?: VoiceTxBufferPreference | null,
+): ResolvedVoiceTxBufferPolicy {
+  const parsedPreference = preference
+    ? VoiceTxBufferPreferenceSchema.safeParse(preference)
+    : null;
+  const normalizedPreference = parsedPreference?.success
+    ? parsedPreference.data
+    : { profile: DEFAULT_VOICE_TX_BUFFER_PROFILE as VoiceTxBufferProfile };
+
+  if (normalizedPreference.profile !== 'custom') {
+    return { ...VOICE_TX_BUFFER_PRESETS[normalizedPreference.profile] };
+  }
+
+  const targetMs = clampVoiceTxBufferValue(normalizedPreference.customTargetBufferMs ?? 90, 40, 500);
+  const minMs = clampVoiceTxBufferValue(targetMs * 0.65, 30, targetMs);
+  const maxMs = clampVoiceTxBufferValue(targetMs * 2.5, targetMs + 40, 900);
+  const headroomMs = clampVoiceTxBufferValue(targetMs * 0.45, 20, 180);
+  const staleFrameMs = clampVoiceTxBufferValue(targetMs * 5, maxMs + 80, 1800);
+  const uplinkMaxBufferedAudioMs = clampVoiceTxBufferValue(targetMs * 2, 80, 1000);
+  const uplinkDegradedBufferedAudioMs = clampVoiceTxBufferValue(
+    targetMs * 4,
+    uplinkMaxBufferedAudioMs + 60,
+    2000,
+  );
+
+  return {
+    profile: 'custom',
+    targetMs,
+    minMs,
+    maxMs,
+    headroomMs,
+    staleFrameMs,
+    uplinkMaxBufferedAudioMs,
+    uplinkDegradedBufferedAudioMs,
+  };
+}
+
 export const RealtimeConnectivityErrorCodeSchema = z.enum([
   'TOKEN_REQUEST_FAILED',
   'SIGNALING_UNREACHABLE',
@@ -27,10 +170,14 @@ export type RealtimeConnectivityErrorCode = z.infer<typeof RealtimeConnectivityE
 
 export const RealtimeConnectivityHintsSchema = z.object({
   signalingUrl: z.string(),
-  signalingPort: z.number().int().positive(),
-  rtcTcpPort: z.number().int().positive(),
-  udpPortRange: z.string(),
-  publicUrlOverrideActive: z.boolean(),
+  localUdpPort: z.number().int().min(1).max(65535),
+  publicCandidateEnabled: z.boolean(),
+  publicEndpoint: z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65535),
+  }).nullable(),
+  iceServers: z.array(z.string()),
+  fallbackTransport: z.literal('ws-compat'),
 });
 export type RealtimeConnectivityHints = z.infer<typeof RealtimeConnectivityHintsSchema>;
 
@@ -45,47 +192,18 @@ export const RealtimeConnectivityIssueSchema = z.object({
 });
 export type RealtimeConnectivityIssue = z.infer<typeof RealtimeConnectivityIssueSchema>;
 
-export const RealtimeTokenRequestSchema = z.object({
-  scope: RealtimeScopeSchema,
-  publish: z.boolean().optional(),
-  previewSessionId: z.string().optional(),
-});
-
-export type RealtimeTokenRequest = z.infer<typeof RealtimeTokenRequestSchema>;
-
 export const RealtimeSessionRequestSchema = z.object({
   scope: RealtimeScopeSchema,
   direction: RealtimeSessionDirectionSchema,
   previewSessionId: z.string().optional(),
   transportOverride: RealtimeTransportKindSchema.optional(),
+  voiceTxBufferPreference: VoiceTxBufferPreferenceSchema.optional(),
+  audioCodecPreference: RealtimeAudioCodecPreferenceSchema.default(DEFAULT_REALTIME_AUDIO_CODEC_PREFERENCE),
+  audioCodecCapabilities: RealtimeAudioCodecCapabilitiesSchema,
 });
 
 export type RealtimeSessionRequest = z.infer<typeof RealtimeSessionRequestSchema>;
 
-export const RealtimeParticipantMetadataSchema = z.object({
-  role: z.string(),
-  tokenId: z.string().nullable().optional(),
-  operatorIds: z.array(z.string()).optional(),
-  clientKind: z.string(),
-  participantKind: RealtimeParticipantKindSchema,
-  scope: RealtimeScopeSchema,
-  previewSessionId: z.string().optional(),
-});
-
-export type RealtimeParticipantMetadata = z.infer<typeof RealtimeParticipantMetadataSchema>;
-
-export const RealtimeTokenResponseSchema = z.object({
-  url: z.string(),
-  roomName: z.string(),
-  token: z.string(),
-  participantIdentity: z.string(),
-  participantName: z.string(),
-  participantMetadata: RealtimeParticipantMetadataSchema,
-  connectivityHints: RealtimeConnectivityHintsSchema,
-});
-
-export type RealtimeTokenResponse = z.infer<typeof RealtimeTokenResponseSchema>;
-
 export const RealtimeTransportOfferSchema = z.object({
   transport: RealtimeTransportKindSchema,
   direction: RealtimeSessionDirectionSchema,
@@ -93,7 +211,6 @@ export const RealtimeTransportOfferSchema = z.object({
   token: z.string(),
   participantIdentity: z.string().nullable().optional(),
   participantName: z.string().nullable().optional(),
-  roomName: z.string().nullable().optional(),
 });
 
 export type RealtimeTransportOffer = z.infer<typeof RealtimeTransportOfferSchema>;
@@ -101,8 +218,74 @@ export type RealtimeTransportOffer = z.infer<typeof RealtimeTransportOfferSchema
 export const RealtimeTransportPolicySchema = z.enum(['auto', 'force-compat']);
 export type RealtimeTransportPolicy = z.infer<typeof RealtimeTransportPolicySchema>;
 
-export const LiveKitNetworkModeSchema = z.enum(['lan', 'internet-auto', 'internet-manual']);
-export type LiveKitNetworkMode = z.infer<typeof LiveKitNetworkModeSchema>;
+function isValidIpv4Literal(value: string): boolean {
+  const parts = value.split('.');
+  return parts.length === 4 && parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part)) {
+      return false;
+    }
+    const parsed = Number.parseInt(part, 10);
+    return parsed >= 0 && parsed <= 255;
+  });
+}
+
+function isValidIpv6Literal(value: string): boolean {
+  if (!value.includes(':') || value.includes('[') || value.includes(']')) {
+    return false;
+  }
+  try {
+    // WHATWG URL parsing gives us a portable IPv6 sanity check without Node-only APIs.
+    // The schema still forbids bracket notation because the setting is host-only.
+    const parsed = new URL(`http://[${value}]/`);
+    return parsed.hostname.length > 2;
+  } catch {
+    return false;
+  }
+}
+
+function isValidDnsHostname(value: string): boolean {
+  if (value.length > 253 || value.endsWith('.')) {
+    return false;
+  }
+  const labels = value.split('.');
+  return labels.every((label) => (
+    label.length >= 1
+    && label.length <= 63
+    && /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label)
+  ));
+}
+
+function isValidRtcDataAudioPublicHost(value: string): boolean {
+  const host = value.trim();
+  if (!host || /\s/.test(host) || /[/?#@]/.test(host) || /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(host)) {
+    return false;
+  }
+  return isValidIpv4Literal(host) || isValidIpv6Literal(host) || isValidDnsHostname(host);
+}
+
+export const RtcDataAudioPublicHostSchema = z.preprocess(
+  (value) => (typeof value === 'string' ? value.trim() : value),
+  z.union([
+    z.literal('').transform(() => null),
+    z.string().min(1).max(253).refine(isValidRtcDataAudioPublicHost, {
+      message: 'Public host must be an IP address or DNS hostname without scheme, port, or path',
+    }),
+    z.null(),
+  ]),
+);
+export type RtcDataAudioPublicHost = z.infer<typeof RtcDataAudioPublicHostSchema>;
+
+export const RtcDataAudioPublicUdpPortSchema = z.preprocess((value) => {
+  if (value === '' || value === undefined) {
+    return null;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : value;
+  }
+  return value;
+}, z.number().int().min(1).max(65535).nullable());
+export type RtcDataAudioPublicUdpPort = z.infer<typeof RtcDataAudioPublicUdpPortSchema>;
 
 export const RealtimeSessionResponseSchema = z.object({
   scope: RealtimeScopeSchema,
@@ -112,47 +295,40 @@ export const RealtimeSessionResponseSchema = z.object({
   selectionReason: z.enum([
     'client-override',
     'server-policy',
-    'bridge-unhealthy',
-    'livekit-disabled',
-    'runtime-unavailable',
-    'default-livekit',
+    'default-rtc-data-audio',
+    'rtc-data-audio-unavailable',
   ]),
   forcedCompatibilityMode: z.boolean(),
   offers: z.array(RealtimeTransportOfferSchema).min(1),
   connectivityHints: RealtimeConnectivityHintsSchema,
+  voiceTxBufferPolicy: ResolvedVoiceTxBufferPolicySchema.optional(),
+  audioCodecPolicy: ResolvedRealtimeAudioCodecPolicySchema,
 });
 
 export type RealtimeSessionResponse = z.infer<typeof RealtimeSessionResponseSchema>;
 
 export const RealtimeSettingsSchema = z.object({
-  publicWsUrl: z.string().url().nullable().optional(),
   transportPolicy: RealtimeTransportPolicySchema.optional(),
-  networkMode: LiveKitNetworkModeSchema.optional(),
-  nodeIp: z.string().nullable().optional(),
+  rtcDataAudioPublicHost: RtcDataAudioPublicHostSchema.optional(),
+  rtcDataAudioPublicUdpPort: RtcDataAudioPublicUdpPortSchema.optional(),
 });
 
 export type RealtimeSettings = z.infer<typeof RealtimeSettingsSchema>;
 
-export const RealtimeCredentialSourceSchema = z.enum(['managed-file', 'environment-override', 'missing']);
-export type RealtimeCredentialSource = z.infer<typeof RealtimeCredentialSourceSchema>;
-
-export const RealtimeCredentialStatusSchema = z.object({
-  initialized: z.boolean(),
-  source: RealtimeCredentialSourceSchema,
-  filePath: z.string().nullable(),
-  apiKeyPreview: z.string().nullable(),
-  createdAt: z.string().nullable(),
-  rotatedAt: z.string().nullable(),
+export const RealtimeRtcDataAudioRuntimeSchema = z.object({
+  localUdpPort: z.number().int().min(1).max(65535),
+  publicCandidateEnabled: z.boolean(),
+  publicEndpoint: z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65535),
+  }).nullable(),
 });
-export type RealtimeCredentialStatus = z.infer<typeof RealtimeCredentialStatusSchema>;
+export type RealtimeRtcDataAudioRuntime = z.infer<typeof RealtimeRtcDataAudioRuntimeSchema>;
 
 export const RealtimeSettingsRuntimeSchema = z.object({
-  liveKitEnabled: z.boolean(),
   connectivityHints: RealtimeConnectivityHintsSchema,
   radioReceiveTransport: RealtimeTransportKindSchema,
-  radioBridgeHealthy: z.boolean(),
-  radioBridgeIssueCode: RealtimeConnectivityErrorCodeSchema.nullable(),
-  credentialStatus: RealtimeCredentialStatusSchema,
+  rtcDataAudio: RealtimeRtcDataAudioRuntimeSchema,
 });
 
 export type RealtimeSettingsRuntime = z.infer<typeof RealtimeSettingsRuntimeSchema>;
@@ -234,6 +410,10 @@ export const RealtimeVoiceTxServerIngressStatsSchema = z.object({
   queueDepthFrames: z.number().int().nonnegative(),
   queuedAudioMs: z.number().nonnegative(),
   droppedFrames: z.number().int().nonnegative(),
+  staleDroppedFrames: z.number().int().nonnegative(),
+  underrunCount: z.number().int().nonnegative(),
+  plcFrames: z.number().int().nonnegative(),
+  jitterTargetMs: z.number().nonnegative(),
 });
 
 export type RealtimeVoiceTxServerIngressStats = z.infer<typeof RealtimeVoiceTxServerIngressStatsSchema>;
@@ -242,8 +422,10 @@ export const RealtimeVoiceTxServerOutputStatsSchema = z.object({
   resampleMs: RealtimeVoiceTxMetricWindowSchema,
   queueWaitMs: RealtimeVoiceTxMetricWindowSchema,
   writeMs: RealtimeVoiceTxMetricWindowSchema,
+  serverPipelineMs: RealtimeVoiceTxMetricWindowSchema,
   endToEndMs: RealtimeVoiceTxMetricWindowSchema,
   outputBufferedMs: RealtimeVoiceTxMetricWindowSchema,
+  outputWriteIntervalMs: RealtimeVoiceTxMetricWindowSchema,
   outputSampleRate: z.number().nullable(),
   outputBufferSize: z.number().nullable(),
   writeFailures: z.number().int().nonnegative(),

package/src/schema/server-message-keys.ts

@@ -18,8 +18,8 @@ export enum ServerMessageKey {
   /** 实时语音连接异常 */
   REALTIME_CONNECTIVITY_WARNING = 'realtimeConnectivityWarning',
 
-  /** 服务端实时语音桥接异常 */
-  REALTIME_BRIDGE_DOWN = 'realtimeBridgeDown',
+  /** 服务端实时语音服务异常 */
+  REALTIME_SERVICE_DOWN = 'realtimeServiceDown',
 
   /** 实时语音链路无音频数据 */
   REALTIME_NO_AUDIO = 'realtimeNoAudio',

package/src/schema/slot-info.schema.ts

@@ -148,7 +148,9 @@ export const SlotPackSchema = z.object({
     /** 去重后的帧数 */
     totalFramesAfterDedup: z.number().default(0),
     /** 最后更新时间戳 */
-    lastUpdated: z.number().default(() => Date.now())
+    lastUpdated: z.number().default(() => Date.now()),
+    /** SlotPack 单调更新序号，用于客户端丢弃乱序旧包 */
+    updateSeq: z.number().int().nonnegative().optional()
   }).default({}),
   /** 解码历史（用于调试） */
   decodeHistory: z.array(z.object({

package/src/schema/websocket.schema.ts

@@ -187,6 +187,7 @@ export enum WSMessageType {
   PLUGIN_USER_ACTION = 'pluginUserAction',
   PLUGIN_PAGE_PUSH = 'pluginPagePush',
   PLUGIN_PANEL_META = 'pluginPanelMeta',
+  PLUGIN_PANEL_CONTRIBUTIONS_CHANGED = 'pluginPanelContributionsChanged',
 
   // ===== OpenWebRX SDR =====
   OPENWEBRX_LISTEN_STATUS = 'openwebrxListenStatus',
@@ -216,7 +217,7 @@ export const SystemStatusSchema = z.object({
   /** 当前电台调制模式（语音模式下使用，如 USB/LSB/FM/AM） */
   currentRadioMode: z.string().optional(),
   /** 引擎状态机当前状态 */
-  engineState: z.enum(['idle', 'waking', 'starting', 'running', 'stopping']).optional(),
+  engineState: z.enum(['idle', 'starting', 'running', 'stopping']).optional(),
   /** 引擎状态机上下文的精简投影 */
   engineContext: z.object({
     error: z.string().optional(),
@@ -1490,6 +1491,7 @@ export interface DigitalRadioEngineEvents {
     data?: unknown;
   }) => void;
   pluginPanelMeta: (data: import('./plugin.schema.js').PluginPanelMetaPayload) => void;
+  pluginPanelContributionsChanged: (data: import('./plugin.schema.js').PluginUIPanelContributionGroup) => void;
 
   // 内部子系统间通信事件（不通过 WebSocket 广播，用于 engine emitter 内部编排）
   encodeStart: (slotInfo: z.infer<typeof SlotInfoSchema>) => void;