/**
 * Promise 风格调用：SDK 方法本身返回 Promise / thenable。
 * 同步异常、Promise reject 与同步返回 `-1` 均收敛为 `HikError`；其它非 thenable 直接 resolve。
 */
export declare function callPromise<T>(sdk: WebVideoCtrlSDK, method: string, ...args: unknown[]): Promise<T>;

/** 同步调用：直接转发 SDK 方法返回值（用于 `I_GetWindowStatus` 等立即返回的 API）。 */
export declare function callSync<T>(sdk: WebVideoCtrlSDK, method: string, ...args: unknown[]): T;

/**
 * 回调式调用：SDK 方法通过 `options.success / options.error` 通知结果。
 *
 * - callback 挂载到 `args` 中最后一个 plain object 上，缺失时自动追加。
 * - 用户预先填的 `success / error` 仍会被调用，但其异常不会污染 Promise 状态。
 * - SDK 同步返回 `-1` 视为立即失败，避免 Promise 永久 pending。
 */
export declare function callWithCallback<T>(sdk: WebVideoCtrlSDK, method: string, ...args: unknown[]): Promise<T>;

export declare interface CaptureOptions {
    /** 文件名；按扩展名决定格式（`.bmp` 为 BMP，其它默认 JPEG）。 */
    fileName?: string;
    windowIndex?: number;
    /** 设置后不再下载文件，而是回传原始 Uint8Array（对应官方 `cbCallback`）。 */
    onData?: (data: Uint8Array) => void | Promise<void>;
}

/** 聚合自模拟 / 数字 / 零通道的通道信息。 */
export declare interface ChannelInfo {
    id: string;
    name: string;
    kind: ChannelKind;
    /** 模拟通道恒为 true，数字通道按 `<online>` 字段判定。 */
    online: boolean;
    /** 仅零通道有意义，模拟/数字均为 true。 */
    enabled: boolean;
    /** 模拟通道独有的视频制式 PAL / NTSC。 */
    videoFormat?: string;
}

export declare type ChannelKind = 'analog' | 'digital' | 'zero';

/** 创建 `HikPlayer` 实例的工厂函数，便于注入 SDK 替身。 */
export declare function createHikPlayer(options?: HikPlayerOptions): HikPlayer;

/** 当前时间字符串，等价于 `formatDate(new Date(), pattern)`。 */
export declare function currentTimestamp(pattern?: string): string;

export declare const DEFAULT_PORT: {
    readonly HTTP: 80;
    readonly HTTPS: 443;
    readonly RTSP: 554;
};

/** 设备端抓图参数（无需先在窗口中预览）。 */
export declare interface DeviceCaptureOptions {
    /** 设备通道号。 */
    channel: number;
    /** 保存文件名；SDK 固定保存为 JPEG。 */
    fileName?: string;
    /** 请求的图片宽度，必须与 `height` 同时传入。 */
    width?: number;
    /** 请求的图片高度，必须与 `width` 同时传入。 */
    height?: number;
    /** 按日期建立子目录，默认 `true`。 */
    byDateDirectory?: boolean;
}

/** 设备登录凭据。 */
export declare interface DeviceCredentials {
    /** 设备 IP 或域名。 */
    host: string;
    /** 端口；默认 `http=80` / `https=443`。 */
    port?: number;
    /** 协议，默认 `http`。 */
    protocol?: ProtocolScheme;
    username: string;
    password: string;
    /** 透传给 `I_Login` 的扩展参数。 */
    login?: DeviceLoginOptions;
}

/** 解析自 `I_GetDeviceInfo` XML 的设备基本信息。 */
export declare interface DeviceInfo {
    deviceName: string;
    deviceId: string;
    deviceType: string;
    model: string;
    serialNumber: string;
    macAddress: string;
    firmwareVersion: string;
    firmwareReleasedDate: string;
    encoderVersion: string;
    encoderReleasedDate: string;
    /** 原始 XML 文档，供进一步解析。 */
    raw: Document;
}

export declare interface DeviceLoginOptions {
    /** 异步交互，默认 `true`。 */
    async?: boolean;
    /** CGI 协议；`1` 强制 ISAPI，缺省由 SDK 自动协商。 */
    cgi?: number;
}

/** `I_GetDevicePort` 返回的端口信息。 */
export declare interface DevicePort {
    /** 设备 HTTP/HTTPS 端口 */
    iDevicePort: number;
    /** 设备 RTSP 端口 */
    iRtspPort: number;
    /** HTTP 管理端口；部分设备与 `iDevicePort` 相同。 */
    iHttpPort?: number;
    /** WebSocket 取流端口（HTTP 页面）。 */
    iWebSocketPort?: number;
    /** WebSocket Secure 取流端口（HTTPS 页面）。 */
    iWebSocketsPort?: number;
}

/** 登录成功返回的会话信息。 */
export declare interface DeviceSession {
    /** 设备唯一标识 `<host>_<port>`。 */
    id: string;
    host: string;
    port: number;
    username: string;
    protocol: ProtocolScheme;
}

export declare interface DownloadByTimeOptions extends DownloadOptions {
    fileName: string;
    startTime: string;
    endTime: string;
}

export declare interface DownloadOptions {
    /** 按日期建立子目录，默认 true。 */
    byDateDirectory?: boolean;
}

/**
 * 将 SDK 回调入参统一为 `Document`。
 *
 * `success(data)` 入参可能形态：
 * - `Document`：现代 SDK 主路径
 * - `string`：早期版本透传 responseText
 * - jQuery `jqXHR`：旧 demo 兼容路径，含 `responseXML` 或 `responseText`
 */
export declare function ensureXmlDocument(input: unknown): Document | null;

/** `I2_OpenFileDlg` 对话框类型（`0` 文件夹，`1` 文件）。 */
export declare const FILE_DIALOG: {
    readonly Directory: 0;
    readonly File: 1;
};

export declare type FileDialogType = typeof FILE_DIALOG[keyof typeof FILE_DIALOG];

/**
 * 按 `yyyy-MM-dd HH:mm:ss[.SSS]` 格式化日期。
 *
 * 支持的 token：`yyyy / MM / dd / HH / mm / ss / SSS`。
 */
export declare function formatDate(date: Date, pattern?: string): string;

/**
 * 海康封装库统一错误类型。
 *
 * 优先用 `code` 做分支判断，避免依赖 `message` 文案；原始错误经由 `cause` 透传（ES2022）。
 */
export declare class HikError extends Error {
    readonly name = "HikError";
    readonly code: HikErrorCode;
    readonly details?: HikErrorDetails;
    constructor(code: HikErrorCode, message: string, details?: HikErrorDetails, cause?: unknown);
}

/**
 * 错误码枚举，用于 `switch` 分支判断与日志聚合。
 *
 * - `SDK_NOT_FOUND`         未检测到 `window.WebVideoCtrl`（多半 `webVideoCtrl.js` 未加载）
 * - `SDK_METHOD_MISSING`    SDK 目标方法不存在（常见于版本不匹配）
 * - `SDK_CALL_FAILED`       SDK 回调 `error` 或抛异常；详情见 `details.status / responseXml`
 * - `NOT_INITIALIZED`       未调用 `init()` 就操作播放器
 * - `ALREADY_INITIALIZED`   已初始化的播放器被重复初始化
 * - `INITIALIZATION_TIMEOUT` 底层播放组件未在指定时间内完成初始化
 * - `INVALID_ARGUMENT`      参数校验失败（如端口越界、时间区间反转）
 * - `DEVICE_NOT_FOUND`      未登录或已登出的设备被引用
 * - `WINDOW_NOT_PLAYING`    对未播放窗口执行 `stop / pause`
 * - `SCRIPT_LOAD_FAILED`    `loadWebVideoCtrl()` 加载脚本失败或超时
 */
export declare type HikErrorCode = 'SDK_NOT_FOUND' | 'SDK_METHOD_MISSING' | 'SDK_CALL_FAILED' | 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INITIALIZATION_TIMEOUT' | 'INVALID_ARGUMENT' | 'DEVICE_NOT_FOUND' | 'WINDOW_NOT_PLAYING' | 'SCRIPT_LOAD_FAILED';

/** 错误附带的调试信息，所有字段均可选。 */
export declare interface HikErrorDetails {
    /** 触发错误的 SDK 方法名 */
    method?: string;
    /** HTTP 状态码（来自 SDK `error(status, xmlDoc)` 回调） */
    status?: number;
    /** 设备返回的 XML 文本（已序列化） */
    responseXml?: string;
    /** SDK 同步返回值（如 `I_Logout` 返回 -1） */
    returnValue?: unknown;
    [key: string]: unknown;
}

/**
 * 海康无插件 WebVideoCtrl 的现代化 TypeScript 客户端。
 *
 * 一个实例对应"一个插件 + 一组登录设备 + 一组播放窗口"。
 * SDK 的同步 / Promise / 回调三种调用形态统一抽象为 `async/await`。
 * 通过 `on/off/once` 订阅强类型事件（同步派发）。
 *
 * 推荐使用 {@link createHikPlayer} 创建实例，便于注入测试 SDK 替身。
 */
export declare class HikPlayer {
    #private;
    constructor(options?: HikPlayerOptions);
    /** 是否已完成初始化。 */
    get isInitialized(): boolean;
    /** 当前选中窗口索引；未初始化时为 0。 */
    get activeWindowIndex(): number;
    /** 已挂载的容器 id；未初始化时为 null。 */
    get containerId(): string | null;
    /** 底层 SDK 实例，供高级扩展使用。 */
    get sdk(): WebVideoCtrlSDK;
    /** 浏览器是否支持无插件模式（Chromium 内核 ≥ 91）。 */
    supportsNoPlugin(): boolean;
    /** 检查官方播放组件版本；无插件模式固定返回 `0`。 */
    checkPluginVersion(): number;
    /**
     * 初始化播放器。
     *
     * 流程：环境校验 → `I_InitPlugin` → `cbInitPluginComplete` 内调用
     * `I_InsertOBJECTPlugin` 挂载到容器。
     */
    init(options: PluginInitOptions): Promise<void>;
    /**
     * 停止全部播放、释放 Worker、清空事件订阅。
     * 重复调用安全；销毁后实例不再可用。适合 SPA 路由切换 / 组件卸载时调用。
     */
    destroy(): Promise<void>;
    /** 调整插件渲染尺寸；不传按容器实际尺寸自适应。 */
    resize(width?: number | string, height?: number | string): void;
    /** 订阅事件，返回取消订阅函数。 */
    on<K extends keyof HikPlayerEventMap>(event: K, handler: (payload: HikPlayerEventMap[K]) => void): () => void;
    /** 仅触发一次，触发后自动解除订阅。 */
    once<K extends keyof HikPlayerEventMap>(event: K, handler: (payload: HikPlayerEventMap[K]) => void): () => void;
    /** 取消订阅；不传 handler 则清空该事件全部监听。 */
    off<K extends keyof HikPlayerEventMap>(event: K, handler?: (payload: HikPlayerEventMap[K]) => void): void;
    /** 切换分屏布局（1=1x1 / 2=2x2 / 3=3x3 / 4=4x4）。 */
    changeLayout(layout: number): Promise<void>;
    /**
     * 进入全屏播放。
     * 官方无插件接口只能进入全屏；传 `false` 时由封装层调用浏览器 Fullscreen API 退出。
     */
    fullScreen(enable?: boolean): Promise<void>;
    /** 获取窗口状态；未播放或越界返回 null。 */
    getWindowStatus(windowIndex?: number): WindowStatus | null;
    /** 全部正在播放的窗口。 */
    getAllWindows(): WindowStatus[];
    /**
     * 登录设备。
     *
     * 返回的 `DeviceSession.id` 即 SDK 内部的 `<host>_<port>` 标识，
     * 后续接口的 `deviceId` 参数均应使用此值。
     */
    login(credentials: DeviceCredentials): Promise<DeviceSession>;
    /** 登出设备，自动停止相关播放窗口并清空 SecretKey。 */
    logout(deviceId: string): Promise<void>;
    /** 已登录设备列表。 */
    listDevices(): DeviceSession[];
    /** 查询设备会话；未登录时返回 undefined。 */
    getDevice(deviceId: string): DeviceSession | undefined;
    /** 设备基本信息（型号、序列号、版本等）。 */
    getDeviceInfo(deviceId: string): Promise<DeviceInfo | null>;
    /** 获取设备安全能力版本 XML。 */
    getSecurityVersion(deviceId: string): Promise<Document | null>;
    /** 同步读取设备 HTTP / RTSP 端口。 */
    getDevicePort(deviceId: string): DevicePort;
    /** 模拟通道（DVR 同轴摄像头）。 */
    getAnalogChannels(deviceId: string): Promise<ChannelInfo[]>;
    /** 数字通道（NVR 接入的网络摄像头）。 */
    getDigitalChannels(deviceId: string): Promise<ChannelInfo[]>;
    /** 零通道（整机预览，NVR/混合 DVR 特有）。 */
    getZeroChannels(deviceId: string): Promise<ChannelInfo[]>;
    /**
     * 一次性获取设备的全部通道（合并模拟 / 数字 / 零）。
     * 任一接口失败仅丢弃该类通道，便于在能力不全的设备上降级。
     */
    getChannels(deviceId: string): Promise<ChannelInfo[]>;
    /** 语音对讲通道列表（保留原始 XML，业务层按需解析）。 */
    getAudioChannels(deviceId: string): Promise<Document | null>;
    /** 开始实时预览。 */
    startPreview(deviceId: string, options: PreviewOptions): Promise<void>;
    /** 停止指定窗口的预览 / 回放，缺省为当前选中窗口。 */
    stop(windowIndex?: number): Promise<void>;
    /** 停止全部窗口（含预览与回放）。 */
    stopAll(): Promise<void>;
    /** 按时间段开始回放；时间格式必须为 `yyyy-MM-dd HH:mm:ss`。 */
    startPlayback(deviceId: string, options: PlaybackOptions): Promise<void>;
    /** 暂停回放。 */
    pause(windowIndex?: number): Promise<void>;
    /** 从暂停 / 单帧恢复正常回放。 */
    resume(windowIndex?: number): Promise<void>;
    /** 加速回放（每次提升一档）。 */
    playFast(windowIndex?: number): Promise<void>;
    /** 减速回放（每次降低一档）。 */
    playSlow(windowIndex?: number): Promise<void>;
    /** 当前窗口的 OSD 时间，格式 `yyyy-MM-dd HH:mm:ss`。 */
    getOsdTime(windowIndex?: number): Promise<string>;
    /** 打开声音。 */
    openSound(windowIndex?: number): Promise<void>;
    /** 关闭声音。 */
    closeSound(windowIndex?: number): Promise<void>;
    /** 设置音量（0-100）。 */
    setVolume(volume: number, windowIndex?: number): Promise<void>;
    /** 启用电子放大。 */
    enableEZoom(windowIndex?: number): Promise<void>;
    /** 禁用电子放大。 */
    disableEZoom(windowIndex?: number): Promise<void>;
    /**
     * 启用 3D 放大。
     * 启用后按住左键从左上拖到右下放大，反之缩小。
     */
    enable3DZoom(windowIndex?: number, onZoomInfo?: (info: unknown) => void): Promise<void>;
    /** 禁用 3D 放大。 */
    disable3DZoom(windowIndex?: number): Promise<void>;
    /** 设置该窗口的码流加密密钥。 */
    setSecretKey(secretKey: string, windowIndex?: number): Promise<void>;
    /**
     * 抓拍当前画面。
     *
     * - 不传 `onData`：保存到浏览器下载文件夹（`.bmp` 抓 BMP，否则 JPEG）。
     * - 传 `onData`：仅回调原始 Uint8Array，不下载文件。
     *
     * @returns SDK 实际使用的文件名
     */
    capture(options?: CaptureOptions): Promise<string>;
    /** 直接从设备通道抓取 JPEG，无需先在播放窗口中预览。 */
    captureDevice(deviceId: string, options: DeviceCaptureOptions): Promise<string>;
    /** 开始本地录像，保存到浏览器下载文件夹。 */
    startRecording(options?: RecordingOptions): Promise<string>;
    /** 停止本地录像。 */
    stopRecording(windowIndex?: number): Promise<void>;
    /**
     * 搜索指定通道、时间段内的录像。
     * SDK 单次最多返回 40 条，`searchPos` 或 `page` 控制翻页；`status` 为 `MORE` 表示仍有后续数据。
     */
    searchRecords(deviceId: string, options: RecordSearchOptions): Promise<RecordSearchResult>;
    /**
     * 按 `playbackURI` 下载录像。
     * V3.4.0 无插件模式通常直接触发浏览器下载并 resolve `undefined`。
     */
    downloadRecord(deviceId: string, playbackUri: string, fileName: string, options?: DownloadOptions): Promise<unknown>;
    /** 按时间段下载录像（需设备支持）。 */
    downloadRecordByTime(deviceId: string, playbackUri: string, options: DownloadByTimeOptions): Promise<unknown>;
    /** 开始 PTZ 动作；松开按键时务必调用 `ptzStop()`，否则球机持续运动。 */
    ptzStart(options: PtzControlOptions): Promise<void>;
    /** 停止 PTZ 动作。 */
    ptzStop(action: PtzControlOptions['action'], windowIndex?: number): Promise<void>;
    /** 保存预置位（先用 PTZ 调整画面，再调用此方法绑定到 ID）。 */
    setPreset(presetId: number, windowIndex?: number): Promise<void>;
    /** 调用预置位。 */
    goPreset(presetId: number, windowIndex?: number): Promise<void>;
    /** 导出设备配置文件（SDK 弹出系统保存框）。 */
    exportDeviceConfig(deviceId: string, password: string): Promise<unknown>;
    /**
     * 导入设备配置文件。
     *
     * `fileName` 与 `file` 通常来自 `openFileDialog(FILE_DIALOG.File)`。
     * V3.4.0 实际上传浏览器 File 句柄，仅传文件名通常无法完成导入。
     */
    importDeviceConfig(deviceId: string, fileName: string, options: ImportDeviceConfigOptions): Promise<unknown>;
    /** 恢复出厂参数（`basic` 保留网络与用户，`full` 全量重置）。 */
    restoreDefault(deviceId: string, mode: RestoreMode): Promise<void>;
    /** 重启设备；成功仅表示设备已收到指令。 */
    restart(deviceId: string): Promise<void>;
    /** 断线重连（不会重新登录）。 */
    reconnect(deviceId: string): Promise<void>;
    /** 开始固件异步升级；升级完成后设备需要重启。`file` 通常来自 `openFileDialog(FILE_DIALOG.File)`。 */
    startUpgrade(deviceId: string, fileName: string, options: StartUpgradeOptions): Promise<unknown>;
    /** 查询升级进度；不传 `deviceId` 时仅在单设备场景自动推断。 */
    getUpgradeProgress(deviceId?: string): Promise<{
        percent: number;
        upgrading: boolean;
    }>;
    /** 透传 ISAPI 请求到设备；登录后已持有认证信息，`auth` 通常无需显式传入。 */
    sendHttpRequest(deviceId: string, uri: string, options?: HttpRequestOptions): Promise<Document | null>;
    /** 通道字符叠加配置（OSD 文字）。 */
    getTextOverlay(deviceId: string, uri: string): Promise<Document | null>;
    /** 打开系统文件 / 文件夹对话框；`szFileName === '-1'` 表示用户取消。 */
    openFileDialog(type: 0 | 1): Promise<OpenFileDialogResult>;
}

/** `on / off / once` 的事件名 → 负载映射；命名规约 `<domain>:<action>`。 */
export declare interface HikPlayerEventMap {
    'plugin:initialized': void;
    'plugin:destroyed': void;
    'plugin:error': {
        windowIndex: number;
        errorCode: number;
        error: unknown;
    };
    'plugin:performance-lack': void;
    'plugin:secret-key-error': {
        windowIndex: number;
    };
    /** 异常事件（取流断开 / 回放结束 / 对讲失败 / 空间不足等）。 */
    'plugin:event': {
        eventType: PluginEventCode | number;
        windowIndex: number;
        param2: number;
    };
    'window:selected': {
        windowIndex: number;
    };
    'window:dblclick': {
        windowIndex: number;
        fullScreen: boolean;
    };
    'device:connected': DeviceSession;
    'device:disconnected': {
        deviceId: string;
    };
    'preview:started': {
        deviceId: string;
        channel: number;
        windowIndex: number;
        zeroChannel: boolean;
    };
    'preview:stopped': {
        deviceId: string;
        windowIndex: number;
    };
    'preview:stopped-all': void;
    'playback:started': {
        deviceId: string;
        channel: number;
        windowIndex: number;
        startTime: string;
        endTime: string;
    };
    'playback:stopped': {
        deviceId: string;
        windowIndex: number;
    };
    'recording:started': {
        fileName: string;
        windowIndex: number;
    };
    'recording:stopped': {
        windowIndex: number;
    };
    'capture:completed': {
        fileName: string;
        windowIndex: number;
        asFile: boolean;
    };
    'device-capture:completed': {
        deviceId: string;
        channel: number;
        fileName: string;
    };
}

export declare interface HikPlayerOptions {
    /** 注入自定义 SDK 实例；缺省读取 `window.WebVideoCtrl`。便于测试替换。 */
    sdk?: WebVideoCtrlSDK;
}

export declare interface HttpRequestOptions {
    /** 默认 `GET`。 */
    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
    /** 请求体（XML 字符串），用于 PUT/POST。 */
    body?: string;
    /** 默认 `true`。 */
    async?: boolean;
    /** `true` 携带已登录设备认证；字符串则直接作为 `auth` 字段透传。 */
    auth?: boolean | string;
}

export declare interface ImportDeviceConfigOptions {
    /** 导入密码；未加密配置可不传。 */
    password?: string;
    /** `openFileDialog(FILE_DIALOG.File)` 返回的 File 句柄（无插件模式必填）。 */
    file: File;
}

/** 标准 DNS 主机名；兼容局域网单标签名称与 punycode 域名。 */
export declare function isHostname(value: string): boolean;

/** 严格匹配点分十进制 IPv4。 */
export declare function isIPv4(value: string): boolean;

/** 校验标准 IPv6（接受带方括号和 IPv4 映射地址）。 */
export declare function isIPv6(value: string): boolean;

/** 不创建实例的情况下检测浏览器是否支持无插件模式。 */
export declare function isNoPluginSupported(): boolean;

/** 主机地址综合校验（IPv4 / IPv6 / 域名 / `localhost`）。 */
export declare function isValidHost(host: string): boolean;

/** 端口号是否合法（1-65535 的整数）。 */
export declare function isValidPort(port: number): boolean;

/** 校验 `[start, end]` 区间合法。 */
export declare function isValidTimeRange(start: string, end: string): boolean;

/**
 * 分屏布局，传给 `I_InitPlugin.iWndowType` 与 `I_ChangeWndNum`。
 *
 * 取值非平方关系：`1/2/3/4` 直接对应 `1x1 / 2x2 / 3x3 / 4x4`，超过 4 按 4x4 处理。
 */
export declare const LAYOUT: {
    readonly Single: 1;
    readonly Quad: 2;
    readonly Nine: 3;
    readonly Sixteen: 4;
};

export declare type Layout = typeof LAYOUT[keyof typeof LAYOUT];

/**
 * 异步加载 `webVideoCtrl.js`，返回 SDK 实例。
 *
 * 已存在 `window.WebVideoCtrl` 时直接复用；否则注入 `<script>` 并等待就绪。
 *
 * 注：SDK 依赖同目录下的 `jsPlugin/`、`encryption/` 等子资源（相对路径请求），
 * 调用者需保证 `scriptUrl` 同级可访问。
 */
export declare function loadWebVideoCtrl(scriptUrl: string, options?: LoadWebVideoCtrlOptions): Promise<WebVideoCtrlSDK>;

export declare interface LoadWebVideoCtrlOptions {
    /** 等待 `window.WebVideoCtrl` 出现的超时时间（毫秒），默认 15000。 */
    timeout?: number;
    /**
     * 同源脚本处理策略。
     * - `'reuse'`（默认）：相同 src 已加载则等待其完成
     * - `'fresh'`：每次插入新 script 节点
     */
    strategy?: 'reuse' | 'fresh';
}

/** 生成 SDK 内部设备标识 `<host>_<port>`。 */
export declare function makeDeviceIdentify(host: string, port: number): string;

/** 校验并返回端口，非法时抛 `INVALID_ARGUMENT`。 */
export declare function normalizePort(port: number): number;

export declare interface OpenFileDialogResult {
    /** 用户选择的文件名；`-1` 表示取消（保留 SDK 原始语义）。 */
    szFileName: string | -1;
    /** 实际文件句柄；选择文件夹时可能为 null。 */
    file: File | null;
}

/** 反解 `<host>_<port>`；缺省端口返回 80。 */
export declare function parseDeviceIdentify(identify: string): {
    host: string;
    port: number;
};

/** 解析 XML 字符串为 `Document`，失败返回 `null`。 */
export declare function parseXml(xml: string | null | undefined): Document | null;

/** `I_GetWindowStatus().iPlayStatus` / `I_GetWndSet()` 元素的播放状态。 */
export declare const PLAY_STATUS: {
    readonly Idle: 0;
    readonly Preview: 1;
    readonly Playback: 2;
    readonly Paused: 3;
    readonly SingleFrame: 4;
    readonly Reverse: 5;
    readonly ReversePaused: 6;
};

export declare interface PlaybackOptions extends Omit<PreviewOptions, 'streamType' | 'zeroChannel'> {
    /** 回放仅支持主码流或子码流。 */
    streamType?: Exclude<StreamType, 3>;
    /** `yyyy-MM-dd HH:mm:ss` 格式。 */
    startTime: string;
    /** `yyyy-MM-dd HH:mm:ss` 格式。 */
    endTime: string;
}

/**
 * 官方文档中的转码回放参数（对应 `oTransCodeParam`）。
 * V3.4.0 无插件实现会拒绝该参数，仅保留此类型供底层兼容场景使用。
 */
export declare interface PlaybackTranscode {
    /** 帧率档位，取值见 `TRANSCODE_FRAME_RATE`。 */
    frameRate?: TranscodeFrameRate;
    /** 分辨率档位，取值见 `TRANSCODE_RESOLUTION`。 */
    resolution?: TranscodeResolution;
    /** 码率档位，取值见 `TRANSCODE_BITRATE`。 */
    bitrate?: TranscodeBitrate;
}

export declare type PlayStatus = typeof PLAY_STATUS[keyof typeof PLAY_STATUS];

/** 插件 `cbEvent` 的事件类型（第一个参数）。 */
export declare const PLUGIN_EVENT: {
    /** 回放异常 / 取流被动断开 */
    readonly PlayAbnormal: 0;
    /** 回放正常结束 */
    readonly PlaybackEnd: 2;
    /** 对讲失败 */
    readonly AudioTalkFail: 3;
    /** 硬盘空间不足 */
    readonly NoFreeSpace: 21;
};

export declare type PluginEventCode = typeof PLUGIN_EVENT[keyof typeof PLUGIN_EVENT];

/**
 * `init()` 参数。仅暴露无插件模式下可配置的字段；
 * SDK 中固定项（`bNoPlugin`、`iPlayMode` 等）由封装层固化。
 */
export declare interface PluginInitOptions {
    /** 渲染容器：DOM 元素、id 字符串或 `#id` 选择器。 */
    container: string | HTMLElement;
    /** 宽度；缺省取容器实际宽度，再退到 800。 */
    width?: number | string;
    /** 高度；缺省取容器实际高度，再退到 600。 */
    height?: number | string;
    /** 初始分屏布局，默认 1（单画面）。 */
    layout?: Layout | number;
    /**
     * 插件背景串，格式：
     * ```
     * plugin-background:#fff; sub-background:#fff; sub-border:#fff; sub-border-select:#fff
     * ```
     */
    colorProperty?: string;
    /** 打开 SDK 调试日志（对应 `bDebugMode`）。 */
    debugMode?: boolean;
    /** 等待底层播放组件完成初始化的毫秒数，默认 `15000`。 */
    timeout?: number;
    /** 窗口选中回调（推荐改用 `on('window:selected')`）。 */
    onWindowSelect?: (windowIndex: number) => void;
    /** 窗口双击 / 全屏回调（推荐改用 `on('window:dblclick')`）。 */
    onWindowDoubleClick?: (windowIndex: number, fullScreen: boolean) => void;
    /** 异常事件（推荐改用 `on('plugin:event')`）。 */
    onEvent?: (eventType: PluginEventCode | number, windowIndex: number, param2: number) => void;
    /** 插件级错误（推荐改用 `on('plugin:error')`）。 */
    onError?: (windowIndex: number, errorCode: number, error: unknown) => void;
    /** 性能不足（推荐改用 `on('plugin:performance-lack')`）。 */
    onPerformanceLack?: () => void;
    /** 码流加密密钥错误（推荐改用 `on('plugin:secret-key-error')`）。 */
    onSecretKeyError?: (windowIndex: number) => void;
}

export declare interface PreviewOptions {
    /** 通道号（来自 `getChannels()` 的 `id` 整数部分）。 */
    channel: number;
    /** 播放窗口索引；缺省使用当前选中窗口。 */
    windowIndex?: number;
    /** 码流类型，默认主码流。 */
    streamType?: StreamType;
    /** 零通道（整机预览），默认 false。 */
    zeroChannel?: boolean;
    /** RTSP 端口；不传由 SDK 自动判断。 */
    rtspPort?: number;
    /** WebSocket 取流端口；V3.4.0 无插件实际读取 `iWSPort`。 */
    webSocketPort?: number;
    /** 走 WebSocket 代理；HTTPS 下及部分设备需置 true。 */
    useProxy?: boolean;
}

/** SDK 内部协议数值；与字符串形态的互转见 `toProtocolValue`。 */
export declare const PROTOCOL: {
    readonly HTTP: 1;
    readonly HTTPS: 2;
};

export declare type Protocol = typeof PROTOCOL[keyof typeof PROTOCOL];

/** 面向用户的协议字符串形态。 */
export declare type ProtocolScheme = 'http' | 'https';

/**
 * PTZ 控制类型，对应 `I_PTZControl` 的 `iPTZIndex`。
 *
 * 海康文档原文：`5-左上，6-左下，7-右上，8-右下`，注意命名顺序与直觉相反。
 */
export declare const PTZ_COMMAND: {
    readonly Up: 1;
    readonly Down: 2;
    readonly Left: 3;
    readonly Right: 4;
    readonly UpLeft: 5;
    readonly DownLeft: 6;
    readonly UpRight: 7;
    readonly DownRight: 8;
    /** 自动巡航开关 */
    readonly AutoPan: 9;
    readonly ZoomIn: 10;
    readonly ZoomOut: 11;
    readonly FocusFar: 12;
    readonly FocusNear: 13;
    readonly IrisOpen: 14;
    readonly IrisClose: 15;
};

/** PTZ 速度合法区间，超出抛出 `INVALID_ARGUMENT`。 */
export declare const PTZ_SPEED_RANGE: {
    readonly min: 1;
    readonly max: 7;
    readonly default: 4;
};

export declare type PtzCommand = typeof PTZ_COMMAND[keyof typeof PTZ_COMMAND];

export declare interface PtzControlOptions {
    /** 控制类型，见 `PTZ_COMMAND`。 */
    action: PtzCommand | number;
    /** 速度 1-7，默认 4。 */
    speed?: number;
    windowIndex?: number;
}

/** `I_RecordSearch` 单次返回上限；分页按此步长递增 `iSearchPos`。 */
export declare const RECORD_SEARCH_PAGE_SIZE = 40;

export declare interface RecordingOptions {
    /** 文件名（无扩展名），缺省自动生成。 */
    fileName?: string;
    windowIndex?: number;
    /** 按日期建立子目录，默认 true。 */
    byDateDirectory?: boolean;
}

/** 录像类型，对应 `metadataDescriptor`。 */
export declare type RecordKind = 'timing' | 'motion' | 'motionOrAlarm' | 'motionAndAlarm' | 'manual' | 'smart' | (string & {});

export declare interface RecordMatch {
    trackId: string;
    /** 起始时间，已规整为 `yyyy-MM-dd HH:mm:ss` */
    startTime: string;
    endTime: string;
    /** 从 `playbackURI` 的 `name=` 抽取，可直接作为下载文件名片段。 */
    fileName: string;
    /** 原始 `playbackURI`，下载录像时须原样回传。 */
    playbackUri: string;
    kind: RecordKind;
}

export declare interface RecordSearchOptions {
    channel: number;
    /** `yyyy-MM-dd HH:mm:ss` 格式。 */
    startTime: string;
    /** `yyyy-MM-dd HH:mm:ss` 格式。 */
    endTime: string;
    /** 录像搜索仅支持主码流或子码流。 */
    streamType?: Exclude<StreamType, 3>;
    /** 搜索起点（必须为 40 的倍数）；优先级高于 `page`。 */
    searchPos?: number;
    /** 1 基页码，自动换算为 `(page-1) * 40`，默认 1。 */
    page?: number;
}

export declare interface RecordSearchResult {
    matches: RecordMatch[];
    /**
     * 后端响应状态：
     * - `OK`         本次为最后一页
     * - `MORE`       仍有后续数据
     * - `NO MATCHES` 时间范围内无录像
     */
    status: 'OK' | 'MORE' | 'NO MATCHES' | (string & {});
    count: number;
    /** 原始 XML，便于业务扩展解析。 */
    raw: Document;
}

/**
 * `I_RestoreDefault` 的 `szMode` 取值。
 * - `basic`：保留用户与网络等基础配置
 * - `full`：完全恢复，包括所有用户信息
 */
export declare const RESTORE_MODE: {
    readonly Basic: "basic";
    readonly Full: "full";
};

export declare interface RestoreDefaultOptions {
    mode: RestoreMode;
}

export declare type RestoreMode = typeof RESTORE_MODE[keyof typeof RESTORE_MODE];

/** 设备/插件运行时错误码与中文描述（来源：`cbPluginErrorHandler` 与流回调 `iErrorCode`）。 */
export declare const SDK_RUNTIME_ERROR: Readonly<{
    1001: "码流传输过程异常";
    1002: "回放结束";
    1003: "取流失败，连接被动断开";
    1004: "对讲连接被动断开";
    1005: "广播连接被动断开";
    1006: "视频编码格式不支持，目前只支持 H.264 / H.265";
    1007: "网络异常导致 WebSocket 断开";
    1008: "首帧回调超时";
    1009: "对讲码流传输过程异常";
    1010: "广播码流传输过程异常";
    1011: "数据接收异常，请检查是否修改了视频格式";
    1012: "播放资源不足";
    1013: "当前环境不支持该鱼眼展开模式";
    1014: "外部强制关闭";
    1015: "获取播放 URL 失败";
    1016: "文件下载完成";
    1017: "密码错误";
    1018: "链接到萤石平台失败";
    1019: "未找到录像片段";
    1020: "水印模式等场景，当前通道需要重新播放";
    1021: "缓存溢出";
    1022: "采集音频失败：非 https/localhost 域名或未插耳机等";
}>;

/** SDK 风格的 success / error 回调容器，所有 options 形式的 API 共享此形态。 */
export declare interface SdkAjaxOptions {
    async?: boolean;
    /** data 可能是 Document、string、jqXHR-like 或 SDK 自定义对象。 */
    success?: (data: unknown) => void;
    /** 首个参数为 HTTP 状态码，第二个为设备 XML（若可获取）。 */
    error?: (status?: number, xmlDoc?: Document | null, nativeError?: unknown) => void;
    [key: string]: unknown;
}

/** `I_GetDevicePort` 返回的端口信息。 */
export declare interface SdkDevicePort {
    iDevicePort: number;
    iRtspPort: number;
    iHttpPort?: number;
    iWebSocketPort?: number;
    iWebSocketsPort?: number;
    [key: string]: unknown;
}

/** `I_SendHTTPRequest` 扩展字段。 */
export declare interface SdkHttpOptions {
    type?: 'GET' | 'POST' | 'PUT' | 'DELETE';
    data?: string;
    /** `true` 携带已登录设备认证；字符串则直接透传。 */
    auth?: boolean | string;
}

/** `I_InitPlugin` 透传参数。 */
export declare interface SdkInitOptions {
    iWndowType?: number;
    bWndFull?: boolean;
    bNoPlugin?: boolean;
    iPlayMode?: number;
    szColorProperty?: string;
    bDebugMode?: boolean;
    cbSelWnd?: (xmlDoc: Document) => void;
    cbDoubleClickWnd?: (windowIndex: number, fullScreen: boolean) => void;
    cbEvent?: (eventType: number, windowIndex: number, param2: number) => void;
    cbInitPluginComplete?: () => void;
    cbPluginErrorHandler?: (windowIndex: number, errorCode: number, error: unknown) => void;
    cbPerformanceLack?: () => void;
    cbSecretKeyError?: (windowIndex: number) => void;
    [key: string]: unknown;
}

export declare type SdkRuntimeError = keyof typeof SDK_RUNTIME_ERROR;

/** `I_GetWindowStatus` / `I_GetWndSet` 返回的窗口信息。 */
export declare interface SdkWindowInfo {
    iIndex: number;
    szIP: string;
    szDeviceIdentify?: string;
    iChannelID: number;
    iPlayStatus: number;
    [key: string]: unknown;
}

export declare interface StartUpgradeOptions {
    /** `openFileDialog(FILE_DIALOG.File)` 返回的 File 句柄（无插件模式必填）。 */
    file: File;
}

/** 码流类型，传给 `I_StartRealPlay` / `I_StartPlayback` / `I_RecordSearch`。 */
export declare const STREAM_TYPE: {
    readonly Main: 1;
    readonly Sub: 2;
    readonly Third: 3;
};

export declare type StreamType = typeof STREAM_TYPE[keyof typeof STREAM_TYPE];

/** XML 文档序列化为字符串；缺失声明时补齐 utf-8。 */
export declare function stringifyXml(doc: Document | null | undefined): string;

/** 当天 `00:00:00` ~ `23:59:59`，便于直接传入回放/搜索接口。 */
export declare function todayTimeRange(): {
    start: string;
    end: string;
};

/** 将任意值收敛为 `HikError`，便于在 `catch` 中统一重抛。 */
export declare function toHikError(error: unknown, fallbackCode?: HikErrorCode, fallbackMessage?: string): HikError;

/** 协议名 → SDK 数值；`'https'` → 2，其它 → 1。 */
export declare function toProtocolValue(protocol: 'http' | 'https'): 1 | 2;

/** 转码回放 `TransBitrate` 档位。 */
export declare const TRANSCODE_BITRATE: {
    readonly K32: "2";
    readonly K48: "3";
    readonly K64: "4";
    readonly K80: "5";
    readonly K96: "6";
    readonly K128: "7";
    readonly K160: "8";
    readonly K192: "9";
    readonly K224: "10";
    readonly K256: "11";
    readonly K320: "12";
    readonly K384: "13";
    readonly K448: "14";
    readonly K512: "15";
    readonly K640: "16";
    readonly K768: "17";
    readonly K896: "18";
    readonly K1024: "19";
    readonly K1280: "20";
    readonly K1536: "21";
    readonly K1792: "22";
    readonly K2048: "23";
    readonly K3072: "24";
    readonly K4096: "25";
    readonly K8192: "26";
    readonly Auto: "255";
};

/** 转码回放 `TransFrameRate` 档位。 */
export declare const TRANSCODE_FRAME_RATE: {
    readonly All: "0";
    readonly Fps1: "5";
    readonly Fps2: "6";
    readonly Fps4: "7";
    readonly Fps6: "8";
    readonly Fps8: "9";
    readonly Fps10: "10";
    readonly Fps12: "11";
    readonly Fps16: "12";
    readonly Fps20: "13";
    readonly Fps15: "14";
    readonly Fps18: "15";
    readonly Fps22: "16";
    readonly Auto: "255";
};

/** 转码回放 `TransResolution` 档位。 */
export declare const TRANSCODE_RESOLUTION: {
    readonly CIF: "1";
    readonly QCIF: "2";
    /** 4CIF / D1 */
    readonly D1: "3";
    readonly Auto: "255";
};

export declare type TranscodeBitrate = typeof TRANSCODE_BITRATE[keyof typeof TRANSCODE_BITRATE];

export declare type TranscodeFrameRate = typeof TRANSCODE_FRAME_RATE[keyof typeof TRANSCODE_FRAME_RATE];

export declare type TranscodeResolution = typeof TRANSCODE_RESOLUTION[keyof typeof TRANSCODE_RESOLUTION];

/** 生成 `<prefix>_<timestamp>_<random>.<ext>` 形式的唯一文件名。 */
export declare function uniqueFileName(prefix: string, extension: string): string;

/**
 * 海康 `window.WebVideoCtrl` 的最小可用类型。
 *
 * 仅声明本封装实际调用的方法；其余接口仍可通过索引签名访问。
 * 命名沿用 SDK 原始 `I_*` / `I2_*` 风格以对照官方文档。
 */
export declare interface WebVideoCtrlSDK {
    /** 浏览器是否支持无插件模式（Chromium 内核 ≥ 91）。 */
    I_SupportNoPlugin: () => boolean;
    /** 初始化插件；无插件模式下 `bNoPlugin / bWndFull / iPlayMode` 由封装层固化。 */
    I_InitPlugin: (width: number | string, height: number | string, options: SdkInitOptions) => void;
    /** 将插件挂载到指定 DOM 容器；`0` 成功，`-1` 失败。 */
    I_InsertOBJECTPlugin: (containerId: string) => number;
    /** 释放底层 Worker / WebSocket 资源。 */
    I_DestroyWorker?: () => void;
    /** 调整插件渲染尺寸（像素）。 */
    I_Resize?: (width: number, height: number) => void;
    /** 切换分屏布局。 */
    I_ChangeWndNum: (layout: number) => Promise<void>;
    /** 查询窗口状态；未播放或越界返回 null。 */
    I_GetWindowStatus: {
        (): SdkWindowInfo[];
        (windowIndex: number): SdkWindowInfo | null;
    };
    /** 获取全部窗口集合。 */
    I_GetWndSet: () => SdkWindowInfo[];
    I_Login: (host: string, protocol: 1 | 2, port: number, username: string, password: string, options: SdkAjaxOptions) => number | void;
    I_Logout: (deviceIdentify: string) => number;
    I_GetDeviceInfo: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_GetDevicePort: (deviceIdentify: string) => SdkDevicePort | null;
    I_GetAnalogChannelInfo: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_GetDigitalChannelInfo: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_GetZeroChannelInfo: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_GetAudioInfo: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_GetSecurityVersion: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_RecordSearch: (deviceIdentify: string, channelId: number, startTime: string, endTime: string, options: SdkAjaxOptions & {
        iStreamType?: number;
        iSearchPos?: number;
    }) => void;
    I_StartRealPlay: (deviceIdentify: string, options: SdkAjaxOptions & Record<string, unknown>) => void;
    I_StartPlayback: (deviceIdentify: string, options: SdkAjaxOptions & Record<string, unknown>) => void;
    I_Stop: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_StopAll: () => Promise<void>;
    I_Pause: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_Resume: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_PlayFast: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_PlaySlow: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_GetOSDTime: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_OpenSound: (windowIndex?: number) => Promise<void>;
    I_CloseSound: (windowIndex?: number) => Promise<void>;
    I_SetVolume: (volume: number, windowIndex?: number) => Promise<void>;
    I_SetSecretKey: (secretKey: string, windowIndex?: number) => Promise<void> | number;
    I_FullScreen: (enable: boolean) => Promise<void>;
    I_EnableEZoom: (windowIndex?: number) => Promise<unknown>;
    I_DisableEZoom: (windowIndex?: number) => Promise<unknown>;
    I_Enable3DZoom: (windowIndex?: number, callback?: (info: unknown) => void) => Promise<unknown>;
    I_Disable3DZoom: (windowIndex?: number) => number;
    I2_CapturePic: (fileName: string, options: {
        iWndIndex?: number;
        cbCallback?: (data: Uint8Array) => void;
    }) => PromiseLike<unknown> | number;
    I_DeviceCapturePic: (deviceIdentify: string, channelId: number, fileName: string, options: {
        bDateDir?: boolean;
        iResolutionWidth?: number;
        iResolutionHeight?: number;
    }) => number;
    I_StartRecord: (fileName: string, options: SdkAjaxOptions & {
        iWndIndex?: number;
        bDateDir?: boolean;
    }) => void;
    I_StopRecord: (options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_StartDownloadRecord: (deviceIdentify: string, playbackUri: string, fileName: string, options: {
        bDateDir?: boolean;
    }) => Promise<unknown>;
    I_StartDownloadRecordByTime: (deviceIdentify: string, playbackUri: string, fileName: string, startTime: string, endTime: string, options: {
        bDateDir?: boolean;
    }) => Promise<unknown>;
    I_PTZControl: (action: number, stop: boolean, options: SdkAjaxOptions & {
        iWndIndex?: number;
        iPTZSpeed?: number;
    }) => void;
    I_SetPreset: (presetId: number, options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_GoPreset: (presetId: number, options: SdkAjaxOptions & {
        iWndIndex?: number;
    }) => void;
    I_ExportDeviceConfig: (deviceIdentify: string, password: string) => Promise<unknown>;
    I_ImportDeviceConfig: (deviceIdentify: string, fileName: string, password?: string, file?: File) => Promise<unknown>;
    I_RestoreDefault: (deviceIdentify: string, mode: 'basic' | 'full', options: SdkAjaxOptions) => void;
    I_Restart: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I_Reconnect: (deviceIdentify: string, options: SdkAjaxOptions) => void;
    I2_StartUpgrade: (deviceIdentify: string, fileName: string, file?: File) => Promise<unknown>;
    I_UpgradeProgress: (deviceIdentify: string) => Promise<{
        percent: number;
        upgrading: boolean;
    }>;
    /** 无插件模式固定返回 `0`；保留用于与官方 SDK 完整对照。 */
    I_CheckPluginVersion: () => number;
    I_SendHTTPRequest: (deviceIdentify: string, uri: string, options: SdkAjaxOptions & SdkHttpOptions) => void;
    I_GetTextOverlay: (uri: string, deviceIdentify: string, options: SdkAjaxOptions) => void;
    I2_OpenFileDlg: (type: 0 | 1) => Promise<{
        szFileName: string | -1;
        file: File | null;
    }>;
    /** 未列出的 `I_*` 方法仍可通过索引签名调用。 */
    [method: string]: unknown;
}

export declare interface WindowStatus {
    index: number;
    deviceId: string;
    channelId: number;
    /** 播放状态枚举，见 `PLAY_STATUS`。 */
    playStatus: number;
    /** SDK 原始对象，包含码流类型、协议等附加字段。 */
    raw: SdkWindowInfo;
}

/** 读取 XML 节点内容；缺失返回 `fallback`。 */
export declare function xmlText(doc: Document | Element | null | undefined, selector: string, fallback?: string): string;

export { }


declare global {
    interface Window {
        /** 由 `webVideoCtrl.js` 注入的全局 SDK 句柄。 */
        WebVideoCtrl?: WebVideoCtrlSDK;
    }
}