@tx5dr/contracts 1.7.12 → 2.5.0

package/src/schema/radio-power.schema.ts

@@ -37,7 +37,9 @@ export const RadioPowerStageSchema = z.enum([
 export type RadioPowerStage = z.infer<typeof RadioPowerStageSchema>;
 
 /**
- * WS event payload: server → client.
+ * Last known power transition state exposed through WebSocket events and
+ * `ctx.radioPower.getState()`. `state` is the controller's high-level state;
+ * `stage` is finer progress; errors use a localized key plus diagnostic detail.
  */
 export const RadioPowerStateEventSchema = z.object({
   profileId: z.string().optional(),
@@ -51,12 +53,17 @@ export const RadioPowerStateEventSchema = z.object({
 export type RadioPowerStateEvent = z.infer<typeof RadioPowerStateEventSchema>;
 
 /**
- * REST request body: POST /api/radio/power
+ * Power targets accepted by Host commands. `on`/`off` control physical power;
+ * `standby`/`operate` switch a responding radio between controller states.
  */
-/** Allowed physical radio target states for a power request. */
 export const RadioPowerTargetSchema = z.enum(['on', 'off', 'standby', 'operate']);
 export type RadioPowerTarget = z.infer<typeof RadioPowerTargetSchema>;
 
+/**
+ * Request to transition one radio profile to a physical/controller power state.
+ * `profileId` selects the profile, `state` is the requested target, and
+ * `autoEngine` controls whether TX-5DR starts after a successful power-on.
+ */
 export const RadioPowerRequestSchema = z.object({
   profileId: z.string().min(1),
   /** Physical radio power target. This is not the TX-5DR software engine state. */
@@ -66,9 +73,7 @@ export const RadioPowerRequestSchema = z.object({
 });
 export type RadioPowerRequest = z.infer<typeof RadioPowerRequestSchema>;
 
-/**
- * REST response: POST /api/radio/power
- */
+/** Result returned by the REST endpoint and `ctx.radioPowerCommands.submit()`. */
 export const RadioPowerResponseSchema = z.object({
   success: z.boolean(),
   target: RadioPowerTargetSchema,
@@ -77,8 +82,10 @@ export const RadioPowerResponseSchema = z.object({
 export type RadioPowerResponse = z.infer<typeof RadioPowerResponseSchema>;
 
 /**
- * REST response: GET /api/radio/power/support?profileId=xxx
- * The server resolves mfgName/modelName internally via HamLib.getSupportedRigs().
+ * Power operations supported by one radio profile, returned by REST and
+ * `ctx.radioPower.getSupport()`. `reason` explains why wake is unavailable;
+ * `supportedStates` lists connected-state transitions the Host may accept.
+ * The Host resolves manufacturer/model names through Hamlib.
  */
 export const RadioPowerSupportInfoSchema = z.object({
   profileId: z.string(),

package/src/schema/radio-profile.schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HamlibConfigSchema } from './radio.schema.js';
 import { AudioDeviceSettingsSchema } from './audio.schema.js';
+import { TxAudioInputSourcePolicySchema } from './tx-audio-input.schema.js';
 
 /**
  * Radio Profile Schema
@@ -14,9 +15,13 @@ export const RadioProfileSchema = z.object({
   radio: HamlibConfigSchema,               // 电台连接配置
   audio: AudioDeviceSettingsSchema,        // 音频设备配置
   audioLockedToRadio: z.boolean(),         // ICOM WLAN = true，音频由电台决定
+  /** Optional policy for the radio's physical TX audio input selector. */
+  txAudioInputSource: TxAudioInputSourcePolicySchema.optional(),
   createdAt: z.number(),
   updatedAt: z.number(),
   description: z.string().optional(),
+  isVirtual: z.boolean().optional(),
+  readOnly: z.boolean().optional(),
 });
 
 export type RadioProfile = z.infer<typeof RadioProfileSchema>;
@@ -41,6 +46,7 @@ export const UpdateProfileRequestSchema = z.object({
   radio: HamlibConfigSchema.optional(),
   audio: AudioDeviceSettingsSchema.optional(),
   audioLockedToRadio: z.boolean().optional(),
+  txAudioInputSource: TxAudioInputSourcePolicySchema.optional(),
   description: z.string().optional(),
 });
 
@@ -52,6 +58,7 @@ export type UpdateProfileRequest = z.infer<typeof UpdateProfileRequestSchema>;
 export const ProfileListResponseSchema = z.object({
   profiles: z.array(RadioProfileSchema),
   activeProfileId: z.string().nullable(),
+  hasConfiguredProfiles: z.boolean().optional().default(false),
 });
 
 export type ProfileListResponse = z.infer<typeof ProfileListResponseSchema>;

package/src/schema/radio.schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { CWKeyActiveLevelSchema } from './cw-keyer.schema.js';
 
 /**
  * 中继差频方向
@@ -10,20 +11,24 @@ export const RepeaterShiftSchema = z.enum(['none', 'minus', 'plus']);
  */
 export const ToneSquelchModeSchema = z.enum(['none', 'ctcss', 'dcs']);
 
-/**
- * 预设频率Schema
- */
+/** Saved dial-frequency preset with band, digital mode and radio modulation. */
 export const PresetFrequencySchema = z.object({
   band: z.string(),
-  mode: z.string(), // 协议模式，如 FT8, FT4
+  mode: z.string(), // 协议模式，如 FT8、FT4、VOICE、SSTV、FAX
   radioMode: z.string().optional(), // 电台调制模式，如 USB, LSB, AM, FM
-  frequency: z.number(),
+  frequency: z.number().int().positive().max(1_000_000_000), // 拨盘频率，单位 Hz（MHz 输入最多 6 位小数）
   description: z.string().optional(),
   repeaterShift: RepeaterShiftSchema.optional(), // 中继差频方向，默认 none
   repeaterOffsetHz: z.number().int().positive().optional(), // 中继偏移，单位 Hz
   toneMode: ToneSquelchModeSchema.optional(), // 哑音类型，默认 none
   ctcssToneTenthsHz: z.number().int().positive().optional(), // CTCSS，单位 0.1Hz
   dcsCode: z.number().int().positive().optional(), // DCS 码
+  region: z.enum(['global', 'iaru1', 'iaru2', 'iaru3']).optional(),
+  imagePurpose: z.enum(['activity', 'iss', 'weatherfax']).optional(),
+  audioCenterHz: z.number().int().positive().optional(),
+  assignedFrequency: z.number().int().positive().max(1_000_000_000).optional(),
+  faxEmission: z.enum(['J3C', 'F3C', 'F1C']).optional(),
+  carrierFrequency: z.number().positive().optional(), // Legacy field; use assignedFrequency for published WEFAX channels.
 }).superRefine((preset, ctx) => {
   const isVoiceFmPreset = preset.mode === 'VOICE' && preset.radioMode?.toUpperCase() === 'FM';
   const hasRepeaterDuplex = preset.repeaterShift === 'minus' || preset.repeaterShift === 'plus';
@@ -192,11 +197,44 @@ export const IcomWlanConfigSchema = z.object({
   dataMode: z.boolean().optional().default(true),
 });
 
+
+/**
+ * TCI / SunSDR 连接配置Schema
+ */
+const TciWebSocketUrlSchema = z.string().url()
+  .refine((value) => /^wss?:\/\//i.test(value), 'TCI URL must use ws:// or wss://')
+  .refine((value) => {
+    const parsed = new URL(value);
+    return !parsed.username && !parsed.password;
+  }, 'TCI URL must not contain credentials');
+
+export const TciConfigSchema = z.object({
+  host: z.string().default('127.0.0.1'),
+  port: z.number().int().min(1).max(65535).default(40001),
+  url: TciWebSocketUrlSchema.optional(),
+  dialect: z.enum([
+    'auto',
+    'expertsdr-1.4',
+    'expertsdr-1.5-1.8',
+    'expertsdr-1.9-2.0',
+    'aethersdr-1.5',
+    'thetis-2.0',
+    'generic-observed',
+  ]).default('auto'),
+  autoDiscoverPorts: z.boolean().default(true),
+  receiver: z.number().int().min(0).default(0),
+  trx: z.number().int().min(0).default(0),
+  vfo: z.number().int().min(0).default(0),
+  audioEnabled: z.boolean().optional().default(true),
+  audioSampleRate: z.number().int().min(8000).max(48000).optional().default(12000),
+});
+
 /**
  * 串口连接配置Schema
  */
 export const SerialConnectionConfigSchema = z.object({
   path: z.string(),
+  serialNumber: z.string().optional(),
   rigModel: z.number().int(),
   serialConfig: SerialConfigSchema.optional(),
   backendConfig: HamlibBackendConfigSchema.optional(),
@@ -206,6 +244,15 @@ export const HamlibSpectrumConfigSchema = z.object({
   speed: z.number().int().min(0).max(255).optional(),
 });
 
+/**
+ * FT8/FT4 数字模式切换频率时的电台 CAT 模式偏好。
+ *
+ * - none: 只切换频率，不主动设置电台模式
+ * - usb: 设置普通 USB
+ * - usb-data: 设置 USB-DATA / PKTUSB 类数据模式
+ */
+export const DigitalModeRadioModePreferenceSchema = z.enum(['none', 'usb', 'usb-data']);
+
 /**
  * PTT (Push-to-Talk) 方法Schema
  *
@@ -216,6 +263,15 @@ export const HamlibSpectrumConfigSchema = z.object({
  */
 export const PttMethodSchema = z.enum(['cat', 'vox', 'dtr', 'rts']);
 
+/**
+ * 虚拟频差（Virtual Frequency Offset / "Fake It" Split）配置Schema
+ * 目标音频频率与滞回区间目前由服务端常量控制（~1500Hz），此处仅暴露开关，预留扩展位。
+ */
+export const FakeFrequencyConfigSchema = z.object({
+  enabled: z.boolean(),
+});
+export type FakeFrequencyConfig = z.infer<typeof FakeFrequencyConfigSchema>;
+
 /**
  * Hamlib配置Schema - 嵌套对象结构
  *
@@ -226,7 +282,7 @@ export const PttMethodSchema = z.enum(['cat', 'vox', 'dtr', 'rts']);
  * - 根据 type 字段读取对应的配置对象
  */
 export const HamlibConfigSchema = z.object({
-  type: z.enum(['none', 'network', 'serial', 'icom-wlan']),
+  type: z.enum(['none', 'network', 'serial', 'icom-wlan', 'tci']),
 
   // 网络模式配置
   network: NetworkConfigSchema.optional(),
@@ -234,17 +290,29 @@ export const HamlibConfigSchema = z.object({
   // ICOM WLAN 模式配置
   icomWlan: IcomWlanConfigSchema.optional(),
 
+  // TCI / SunSDR 模式配置
+  tci: TciConfigSchema.optional(),
+
   // 串口模式配置
   serial: SerialConnectionConfigSchema.optional(),
 
   // Hamlib 频谱配置（当前仅用于官方频谱流 speed）
   spectrum: HamlibSpectrumConfigSchema.optional(),
 
+  // FT8/FT4 切换频率时是否主动设置电台 CAT 模式；未设置时按 none 处理
+  digitalModeRadioMode: DigitalModeRadioModePreferenceSchema.optional(),
+
   // 发射时序补偿（毫秒）- 用于补偿电台和网络的处理延迟
   // 正值表示提前发射，负值表示延后发射
   // 范围限制：-1000~1000ms，适用于各种网络和设备延迟场景
   transmitCompensationMs: z.number().int().min(-1000).max(1000).optional(),
 
+  // 虚拟频差（Virtual Frequency Offset / WSJT-X "Fake It" Split）
+  // 启用后，发射时临时反向平移电台 dial 频率，使送进电台的音频载波保持在甜区(~1500Hz)，
+  // 而打到空中的实际 RF 位置与用户设定的发射频点完全一致。
+  // 用于规避部分电台在音频频率过高/过低时发射功率衰减的问题；对用户透明（接收 dial、TX 标记不变）。
+  fakeFrequency: FakeFrequencyConfigSchema.optional(),
+
   // PTT 方法（默认 'cat'，即 Hamlib RIG 类型）
   // 仅对 network 和 serial 连接类型有效，icom-wlan 固定使用 CI-V PTT
   pttMethod: PttMethodSchema.optional(),
@@ -258,6 +326,9 @@ export const HamlibConfigSchema = z.object({
 
   // CW 键控引脚类型（dtr 或 rts）
   cwKeyMethod: z.enum(['dtr', 'rts']).optional(),
+
+  // CW 键控有效电平（默认 high，即高电平按下；部分接口为低电平按下）
+  cwKeyActiveLevel: CWKeyActiveLevelSchema.optional(),
 });
 
 /**
@@ -303,7 +374,7 @@ export const RadioInfoSchema = z.object({
   /** Hamlib 电台型号 ID (serial/network 模式使用，icom-wlan 模式可选) */
   rigModel: z.number().optional(),
   /** 连接类型 */
-  connectionType: z.enum(['serial', 'network', 'icom-wlan']),
+  connectionType: z.enum(['serial', 'network', 'icom-wlan', 'tci']),
   /** 固件版本 (如果可获取) */
   firmwareVersion: z.string().optional(),
   /** 序列号 (如果可获取) */
@@ -315,6 +386,7 @@ export const RadioInfoSchema = z.object({
  */
 export const SerialPortSchema = z.object({
   path: z.string(),
+  friendlyName: z.string().optional(),
   manufacturer: z.string().optional(),
   serialNumber: z.string().optional(),
   pnpId: z.string().optional(),
@@ -336,6 +408,7 @@ export const SerialPortsResponseSchema = z.object({
 export const TestResponseSchema = z.object({
   success: z.boolean(),
   message: z.string().optional(),
+  details: z.record(z.unknown()).optional(),
 });
 
 /**
@@ -449,6 +522,14 @@ export const CustomFrequencyPresetsSchema = z.object({
   presets: z.array(PresetFrequencySchema).min(1),
 });
 
+/** TCI receiver DDS/IQ center-frequency control request. */
+export const DdsFrequencyRequestSchema = z.object({
+  frequency: z.number().finite().nonnegative(),
+  receiver: z.number().int().nonnegative().optional(),
+});
+
+export type DdsFrequencyRequest = z.infer<typeof DdsFrequencyRequestSchema>;
+
 // 导出类型
 export type CustomFrequencyPresets = z.infer<typeof CustomFrequencyPresetsSchema>;
 export type PresetFrequency = z.infer<typeof PresetFrequencySchema>;
@@ -461,8 +542,10 @@ export type HamlibConfigFieldType = z.infer<typeof HamlibConfigFieldTypeSchema>;
 export type HamlibConfigField = z.infer<typeof HamlibConfigFieldSchema>;
 export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
 export type IcomWlanConfig = z.infer<typeof IcomWlanConfigSchema>;
+export type TciConfig = z.infer<typeof TciConfigSchema>;
 export type SerialConnectionConfig = z.infer<typeof SerialConnectionConfigSchema>;
 export type HamlibSpectrumConfig = z.infer<typeof HamlibSpectrumConfigSchema>;
+export type DigitalModeRadioModePreference = z.infer<typeof DigitalModeRadioModePreferenceSchema>;
 export type PttMethod = z.infer<typeof PttMethodSchema>;
 export type HamlibConfig = z.infer<typeof HamlibConfigSchema>;
 export type RadioConfigResponse = z.infer<typeof RadioConfigResponseSchema>;

package/src/schema/realtime.schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export const RealtimeScopeSchema = z.enum(['radio', 'openwebrx-preview']);
 export type RealtimeScope = z.infer<typeof RealtimeScopeSchema>;
 
-export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat']);
+export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat', 'android-native']);
 export type RealtimeTransportKind = z.infer<typeof RealtimeTransportKindSchema>;
 
 export const RealtimeSessionDirectionSchema = z.enum(['recv', 'send']);
@@ -307,6 +307,13 @@ export const RealtimeSessionResponseSchema = z.object({
 
 export type RealtimeSessionResponse = z.infer<typeof RealtimeSessionResponseSchema>;
 
+/**
+ * Persisted realtime-audio transport preferences.
+ *
+ * `transportPolicy` selects automatic or explicit transport behavior. The
+ * optional public host/UDP port advertise an RTC data-audio endpoint to remote
+ * clients; null/omitted values disable that public candidate.
+ */
 export const RealtimeSettingsSchema = z.object({
   transportPolicy: RealtimeTransportPolicySchema.optional(),
   rtcDataAudioPublicHost: RtcDataAudioPublicHostSchema.optional(),
@@ -333,6 +340,7 @@ export const RealtimeSettingsRuntimeSchema = z.object({
 
 export type RealtimeSettingsRuntime = z.infer<typeof RealtimeSettingsRuntimeSchema>;
 
+/** Realtime settings plus the Host's current resolved runtime projection. */
 export const RealtimeSettingsResponseDataSchema = RealtimeSettingsSchema.extend({
   runtime: RealtimeSettingsRuntimeSchema.optional(),
 });

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

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { DxccStatusSchema, SubdivisionConfidenceSchema } from './qso.schema.js';
 
+/** Number of non-empty slot packs retained for live FT8/FT4 message history. */
+export const SLOT_PACK_HISTORY_LIMIT = 1000;
+
 /**
  * Frequency context captured when a slot pack is created.
  * Fields are optional so older persisted slot packs remain valid.
@@ -16,11 +19,12 @@ export const SlotPackFrequencyContextSchema = z.object({
 export type SlotPackFrequencyContext = z.infer<typeof SlotPackFrequencyContextSchema>;
 
 /**
- * 时隙周期（偶数奇数）
- */
-
-/**
- * 时隙信息
+ * Timing and identity of one FT8/FT4 receive or transmit slot.
+ *
+ * `startMs` is the calibrated Unix epoch start in milliseconds; `phaseMs` is
+ * elapsed time inside the slot; `driftMs` is the clock correction; `cycleNumber`
+ * is the absolute slot index (use modulo two for even/odd); and `utcSeconds` is
+ * the integer epoch-second form used for display and logs.
  */
 export const SlotInfoSchema = z.object({
   /** 时隙唯一标识符 */
@@ -41,9 +45,7 @@ export const SlotInfoSchema = z.object({
 
 export type SlotInfo = z.infer<typeof SlotInfoSchema>;
 
-/**
- * 基于日志本的消息分析结果
- */
+/** Logbook-derived enrichment attached to a decoded message when available. */
 export const LogbookAnalysisSchema = z.object({
   /** 是否为新呼号（之前没有通联过） */
   isNewCallsign: z.boolean().optional(),
@@ -76,7 +78,9 @@ export const LogbookAnalysisSchema = z.object({
 export type LogbookAnalysis = z.infer<typeof LogbookAnalysisSchema>;
 
 /**
- * FT8 帧数据
+ * Original decoder frame with RF metrics and unparsed message text.
+ * `snr` is dB, `freq` is audio offset in hertz, `dt` is seconds, and
+ * `confidence` is normalized to 0..1.
  */
 export const FrameMessageSchema = z.object({
   /** 信号强度 (dB) */
@@ -92,7 +96,8 @@ export const FrameMessageSchema = z.object({
   /** 基于日志本的分析结果（可选，仅在客户端定制化数据中提供） */
   logbookAnalysis: LogbookAnalysisSchema.optional(),
   /** 操作员ID（可选，仅 TX 帧使用，用于多操作员覆盖识别） */
-  operatorId: z.string().optional()
+  operatorId: z.string().optional(),
+  streamId: z.string().optional(),
 });
 
 export type FrameMessage = z.infer<typeof FrameMessageSchema>;
@@ -157,7 +162,9 @@ export const DecodeResultSchema = z.object({
 export type DecodeResult = z.infer<typeof DecodeResultSchema>;
 
 /**
- * 时隙封装信息（去重和多次解码取优）
+ * Deduplicated best-frame collection for one slot, including decode statistics,
+ * history and the dial-frequency context captured when the slot began.
+ * `startMs`, `endMs` and history timestamps use Unix epoch milliseconds.
  */
 export const SlotPackSchema = z.object({
   /** 时隙ID */

package/src/schema/spectrum-config.schema.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+
+export const SpectrumPresetIdSchema = z.enum(['responsive', 'balanced', 'fine']);
+export const SpectrumPresetSchema = z.enum(['responsive', 'balanced', 'fine', 'custom']);
+export type SpectrumPreset = z.infer<typeof SpectrumPresetSchema>;
+export type SpectrumPresetId = z.infer<typeof SpectrumPresetIdSchema>;
+
+export const SpectrumWindowFunctionSchema = z.enum([
+  'hann',
+  'hamming',
+  'blackman',
+  'blackmanHarris',
+  'none',
+]);
+export type SpectrumWindowFunction = z.infer<typeof SpectrumWindowFunctionSchema>;
+
+export const SpectrumFftSizeSchema = z.union([
+  z.literal(1024),
+  z.literal(2048),
+  z.literal(4096),
+  z.literal(8192),
+  z.literal(16384),
+]);
+
+export const SpectrumTargetSampleRateSchema = z.union([
+  z.literal(3000),
+  z.literal(4000),
+  z.literal(6000),
+  z.literal(8000),
+  z.literal(12000),
+]);
+
+export const SpectrumCustomSettingsSchema = z.object({
+  analysisIntervalMs: z.number().int().min(50).max(1000),
+  fftSize: SpectrumFftSizeSchema,
+  targetSampleRate: SpectrumTargetSampleRateSchema,
+  windowFunction: SpectrumWindowFunctionSchema,
+  haloReduce: z.boolean(),
+});
+export type SpectrumCustomSettings = z.infer<typeof SpectrumCustomSettingsSchema>;
+
+export const SpectrumRenderFrequencyRangeSchema = z.object({
+  min: z.number().finite(),
+  max: z.number().finite(),
+}).refine((range) => range.max > range.min, {
+  message: 'Spectrum frequency range maximum must be greater than minimum',
+  path: ['max'],
+});
+
+export const SpectrumRenderConfigSchema = z.object({
+  preset: SpectrumPresetSchema,
+  revision: z.number().int().nonnegative(),
+  analysisIntervalMs: z.number().int().positive(),
+  frameRateHz: z.number().positive(),
+  fftSize: z.number().int().positive(),
+  targetSampleRate: z.number().int().positive(),
+  fftWindowDurationMs: z.number().positive(),
+  frequencyResolutionHz: z.number().positive(),
+  frequencyRange: SpectrumRenderFrequencyRangeSchema,
+  displayBinCount: z.number().int().positive(),
+  windowFunction: SpectrumWindowFunctionSchema,
+  haloReduce: z.boolean(),
+  customSettings: SpectrumCustomSettingsSchema.optional(),
+});
+export type SpectrumRenderConfig = z.infer<typeof SpectrumRenderConfigSchema>;
+
+export const TciIqSampleRateSchema = z.number().int().positive();
+export type TciIqSampleRate = z.infer<typeof TciIqSampleRateSchema>;
+
+export const TciSpectrumSettingsSchema = z.object({
+  fftSize: z.union([
+    z.literal(4096), z.literal(8192), z.literal(16384), z.literal(32768), z.literal(65536),
+  ]),
+  displayBinCount: z.number().int().min(1024).max(16384),
+  analysisIntervalMs: z.number().int().min(20).max(1000),
+});
+export type TciSpectrumSettings = z.infer<typeof TciSpectrumSettingsSchema>;
+
+export const TciSpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  settings: TciSpectrumSettingsSchema,
+});
+export type TciSpectrumSettingsResponse = z.infer<typeof TciSpectrumSettingsResponseSchema>;
+
+export const TciIqSpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  configuredSampleRate: TciIqSampleRateSchema.nullable(),
+  appliedSampleRate: TciIqSampleRateSchema.nullable(),
+  supportedSampleRates: z.array(TciIqSampleRateSchema),
+});
+export type TciIqSpectrumSettingsResponse = z.infer<typeof TciIqSpectrumSettingsResponseSchema>;
+
+export const SpectrumPresetDefinitionSchema = SpectrumRenderConfigSchema.omit({
+  revision: true,
+});
+export type SpectrumPresetDefinition = z.infer<typeof SpectrumPresetDefinitionSchema>;
+
+export const SPECTRUM_PRESET_DEFINITIONS: Record<SpectrumPresetId, SpectrumPresetDefinition> = {
+  responsive: {
+    preset: 'responsive',
+    analysisIntervalMs: 100,
+    frameRateHz: 10,
+    fftSize: 2048,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (2048 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 2048,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 1025,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+  balanced: {
+    preset: 'balanced',
+    analysisIntervalMs: 150,
+    frameRateHz: 1000 / 150,
+    fftSize: 8192,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (8192 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 8192,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 4097,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+  fine: {
+    preset: 'fine',
+    analysisIntervalMs: 200,
+    frameRateHz: 5,
+    fftSize: 16384,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (16384 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 16384,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 8193,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+};
+
+export function getSpectrumPresetDefinition(preset: SpectrumPresetId): SpectrumPresetDefinition {
+  return { ...SPECTRUM_PRESET_DEFINITIONS[preset] };
+}
+
+export const SpectrumSettingsUpdateRequestSchema = z.discriminatedUnion('preset', [
+  z.object({ preset: SpectrumPresetIdSchema }),
+  z.object({ preset: z.literal('custom'), settings: SpectrumCustomSettingsSchema }),
+]);
+export type SpectrumSettingsUpdateRequest = z.infer<typeof SpectrumSettingsUpdateRequestSchema>;
+
+export const SpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  currentSettings: SpectrumRenderConfigSchema,
+  presets: z.array(SpectrumPresetDefinitionSchema),
+});
+export type SpectrumSettingsResponse = z.infer<typeof SpectrumSettingsResponseSchema>;