Central Control Client

中控控制协议 V3.0.6 Node.js TypeScript 客户端库。

功能特性

• 完整的V3.0.6协议支持
• TypeScript类型安全
• 模块化设计，易于扩展
• TCP/UDP双协议支持
• 自动重连机制
• 事件驱动架构
• 完善的错误处理

安装

npm install central-control-client

快速开始

import { CentralControlClient } from 'central-control-client';

async function main() {
  // 创建客户端实例
  const client = new CentralControlClient({
    host: '192.168.1.100', // 中控服务器IP
    tcpPort: 3011,         // TCP端口（默认3011）
    udpPort: 3012,         // UDP端口（默认3012）
    timeout: 5000,         // 超时时间（毫秒）
    autoReconnect: true    // 自动重连
  });

  // 连接服务器
  const connected = await client.connect();
  if (!connected) {
    console.error('连接失败');
    return;
  }

  console.log('连接成功！');

  // 播放视频
  await client.playVideoFile('demo.mp4');

  // 获取视频状态
  const status = await client.video.getStatus();
  console.log('视频状态:', status);

  // 显示图片
  await client.showImageFile('background.jpg');

  // 播放节目
  await client.program.playProject('P1');

  // 调整音量
  await client.volume.increaseSystemVolume(10);

  // 断开连接
  client.disconnect();
}

main().catch(console.error);

可选协议连接

客户端支持可选地连接TCP或UDP协议，您可以根据需要选择连接其中一种或两种协议。

只连接TCP协议

const client = new CentralControlClient({
  host: '192.168.1.100',
  tcpPort: 3011,
  protocols: ['tcp'] // 只连接TCP
});

await client.connect();
console.log('TCP连接状态:', client.isTCPConnected()); // true
console.log('UDP连接状态:', client.isUDPConnected()); // false

只连接UDP协议

const client = new CentralControlClient({
  host: '192.168.1.100',
  udpPort: 3012,
  protocols: ['udp'] // 只连接UDP
});

await client.connect();
console.log('TCP连接状态:', client.isTCPConnected()); // false
console.log('UDP连接状态:', client.isUDPConnected()); // true

同时连接TCP和UDP（默认）

const client = new CentralControlClient({
  host: '192.168.1.100',
  tcpPort: 3011,
  udpPort: 3012,
  protocols: ['tcp', 'udp'] // 同时连接TCP和UDP（默认值）
});

await client.connect();
console.log('TCP连接状态:', client.isTCPConnected()); // true
console.log('UDP连接状态:', client.isUDPConnected()); // true

连接状态检查

// 检查整体连接状态
if (client.isConnected()) {
  console.log('客户端已连接到服务器');
}

// 检查特定协议连接状态
if (client.isTCPConnected()) {
  console.log('TCP连接已建立');
  await client.sendCustomCommand('videoPlay'); // 发送TCP命令
}

if (client.isUDPConnected()) {
  console.log('UDP连接已建立');
  await client.sendUDPCommand('videoPlay'); // 发送UDP命令
}

API文档

CentralControlClient

主客户端类，提供所有控制功能。

构造函数

new CentralControlClient(options: ConnectionOptions)

连接选项

interface ConnectionOptions {
  host: string;                    // 服务器地址
  tcpPort?: number;               // TCP端口，默认3011
  udpPort?: number;               // UDP端口，默认3012
  timeout?: number;               // 超时时间，默认5000ms
  autoReconnect?: boolean;        // 自动重连，默认true
  reconnectInterval?: number;     // 重连间隔，默认3000ms
  protocols?: ProtocolType[];     // 连接协议，默认['tcp', 'udp']
}

type ProtocolType = 'tcp' | 'udp';

主要方法

• connect(): Promise<boolean> - 连接服务器
• disconnect(): void - 断开连接
• isConnected(): boolean - 检查整体连接状态
• isTCPConnected(): boolean - 检查TCP连接状态
• isUDPConnected(): boolean - 检查UDP连接状态
• sendCustomCommand(command: string): Promise<Response> - 发送自定义命令（TCP）
• sendUDPCommand(command: string): Promise<void> - 发送UDP命令
• playVideoFile(fileName: string): Promise<Response> - 播放视频文件（快捷方法）
• showImageFile(fileName: string): Promise<Response> - 显示图片文件（快捷方法）
• togglePlayPause(): Promise<Response> - 切换播放/暂停（快捷方法）

命令模块

客户端提供多个命令模块，每个模块负责特定类型的控制：

视频控制 (client.video)

// 基本控制
await client.video.updateVideo('video.mp4');  // 更新视频
await client.video.play();                    // 播放
await client.video.pause();                   // 暂停
await client.video.stop();                    // 停止
await client.video.previous();                // 上一个
await client.video.next();                    // 下一个

// 播放模式
await client.video.setSinglePlay();           // 单曲播放
await client.video.setListPlay();             // 列表播放

// 播放结束行为
import { VideoEndAction } from 'central-control-client';
await client.video.setEndAction(VideoEndAction.LOOP);      // 循环
await client.video.setEndAction(VideoEndAction.FIRST_FRAME); // 停在第一帧
await client.video.setEndAction(VideoEndAction.LAST_FRAME);  // 停在最后一帧
await client.video.setEndAction(VideoEndAction.STOP);      // 停止

// 状态查询
const status = await client.video.getStatus();    // 获取视频状态
const mediaList = await client.video.getMediaList(); // 获取媒体列表

// 同步模式
await client.video.setSyncMode(true);  // 启用同步
await client.video.setSyncMode(false); // 禁用同步

图片控制 (client.image)

await client.image.updateImage('image.jpg');  // 更新图片
await client.image.play();                    // 播放
await client.image.stop();                    // 停止
await client.image.startLoop();               // 开始循环
await client.image.stopLoop();                // 停止循环
await client.image.previous();                // 上一个
await client.image.next();                    // 下一个

节目控制 (client.program)

await client.program.playProject('P1');       // 播放节目
await client.program.pauseProject();          // 暂停节目
await client.program.stopProject();           // 停止节目
await client.program.nextProject();           // 下一个节目
await client.program.previousProject();       // 上一个节目

// 窗口控制
await client.program.playForm('Form1', 'Project1');   // 播放窗口
await client.program.pauseForm('Form1', 'Project1');  // 暂停窗口
await client.program.stopForm('Form1');               // 停止窗口

// 静音控制
import { MuteState } from 'central-control-client';
await client.program.muteForm('Form1', MuteState.MUTE);    // 静音
await client.program.muteForm('Form1', MuteState.UNMUTE);  // 取消静音

模式切换 (client.mode)

await client.mode.setMediaMode();             // 媒体模式
await client.mode.setCaptureDesktop();        // 捕获桌面模式
await client.mode.setOutputDesktop();         // 输出桌面模式

音量控制 (client.volume)

await client.volume.increaseSystemVolume(10); // 增加10%音量
await client.volume.decreaseSystemVolume(10); // 减少10%音量

import { MuteState } from 'central-control-client';
await client.volume.muteSystemVolume(MuteState.MUTE);    // 静音系统音量
await client.volume.muteSystemVolume(MuteState.UNMUTE);  // 取消静音

工具命令 (client.utility)

// 坐标模式
import { CoordinateMode } from 'central-control-client';
await client.utility.setCoordinateMode(CoordinateMode.COD_2D);      // 2D模式
await client.utility.setCoordinateMode(CoordinateMode.COD_3D);      // 3D模式
await client.utility.setCoordinateMode(CoordinateMode.COD_DEFAULT); // 默认模式

// 背景图片
await client.utility.changeBackgroundImage('bg.jpg');      // 临时更换
await client.utility.changeBackgroundImage('bg.jpg', true); // 永久更换

// 3D模式
import { ThreeDMode } from 'central-control-client';
await client.utility.setThreeDMode(ThreeDMode.LR);        // 左右3D
await client.utility.setThreeDMode(ThreeDMode.UD);        // 上下3D
await client.utility.setThreeDMode(ThreeDMode.DISABLED);  // 禁用3D

// 系统控制
await client.utility.shutdown();              // 关机
await client.utility.restartServer();         // 重启服务器
await client.utility.changeConfigFile('config.xml'); // 更改配置文件
await client.utility.minimizeWindow();        // 最小化窗口
await client.utility.restoreWindow();         // 恢复窗口

事件监听

// 连接事件
client.connection.on('connected', () => {
  console.log('已连接到服务器');
});

client.connection.on('disconnected', () => {
  console.log('与服务器断开连接');
});

client.connection.on('error', (error) => {
  console.error('连接错误:', error);
});

// 数据接收
client.connection.on('tcpData', (data) => {
  console.log('TCP数据:', data);
});

client.connection.on('udpData', (data) => {
  console.log('UDP数据:', data);
});

高级用法

批量操作

class PresentationController {
  constructor(private client: CentralControlClient) {}

  async startPresentation() {
    // 切换到媒体模式
    await this.client.mode.setMediaMode();
    
    // 播放开场视频
    await this.client.video.updateVideo('opening.mp4');
    await this.client.video.play();
    
    // 等待视频播放完毕
    await this.waitForVideoComplete();
    
    // 切换到图片轮播
    await this.client.image.updateImage('slide1.jpg');
    await this.client.image.startLoop();
    
    // 调整音量
    await this.client.volume.increaseSystemVolume(50);
  }

  private async waitForVideoComplete(): Promise<void> {
    return new Promise((resolve) => {
      const checkInterval = setInterval(async () => {
        const status = await this.client.video.getStatus();
        if (!status?.isPlaying) {
          clearInterval(checkInterval);
          resolve();
        }
      }, 1000);
    });
  }
}

错误处理

async function safeOperation(operation: () => Promise<any>) {
  try {
    const result = await operation();
    console.log('操作成功:', result);
    return result;
  } catch (error) {
    console.error('操作失败:', error);
    
    // 重试逻辑
    console.log('正在重试...');
    try {
      const retryResult = await operation();
      console.log('重试成功:', retryResult);
      return retryResult;
    } catch (retryError) {
      console.error('重试失败:', retryError);
      throw retryError;
    }
  }
}

// 使用
await safeOperation(() => client.video.play());

开发

构建

npm run build

开发模式

npm run dev

运行示例

npm run example

许可证

MIT