ꂃ ꁹ

相机控制协议:HTTP 命令参考

DriftSee 开发者文档 · 2026.11.18

查询相机配网、预览、拍录、参数及媒体文件管理的 HTTP 命令。

下载 SDK 开发包 · 75.55 MB

提取码:gnts · SDK 1.0.0 · 开发预览 · Android / iOS

XL Pro / X5 / X5 Mini 接入要求

连接前先读取相机型号和固件版本。手机与相机须位于可互通的局域网;相机发现使用 UDP 5555。已知 IP 时可直接连接。

建议先使用 720P、30 帧/秒、2 Mbps 视频配置,联通后再按目标型号和固件支持的档位调整。分辨率、帧率和码率应显式填写,避免不同配网入口的默认值差异。

以下参数已按当前三个型号的代码路径核对。型号与固件可能影响单位和生效条件;每次设置后读取 get_camera_status 确认实际值。

型号 2 Mbps 示例与改参要求
XL Pro HTTP: stream_bitrate=250000 Byte/s
停止录像;副码流还受主录像分辨率和 hd_record 设置约束。
X5 HTTP: stream_bitrate=2000000 bit/s
停止录像、RTSP 预览和 RTMP 推流,在主码流待机状态修改。
X5 Mini HTTP: stream_bitrate=2000000 bit/s
停止录像、RTSP 预览和 RTMP 推流,在主码流待机状态修改。

码率单位与数值边界

入口 / 参数 单位与示例
fmcam.conf: stream_bitrate 三个型号均为 bit/s;2000000 = 2 Mbps。
start_rtmp_with_param ... &stream_bitrate= 三个型号均按配置文件使用 bit/s;2000000 = 2 Mbps。
HTTP: stream_bitrate= XL Pro 为 Byte/s;X5 / X5 Mini 当前代码为 bit/s,按上表填写。
HTTP: video_bitrate= 三个型号均为 Byte/s;500000 = 4 Mbps。
get_camera_status: stream_bitrate 返回实际编码码率,单位为 bit/s。

独立 HTTP 流码率参数应为正整数。XL Pro 的有效边界为大于 12500、至 5625000 Byte/s;X5 / X5 Mini 为 100000~45000000 bit/s。这些是代码的数值边界;首次联调请使用上表的 2 Mbps 配置,并根据网络与画面效果调整。

分辨率与帧率写法

视频配置 配置文件 / RTMP 启动参数与独立 HTTP 参数
1080P stream_resolution=1080P
HTTP: stream_res=3
720P stream_resolution=720P
HTTP: stream_res=4
WVGA stream_resolution=WVGA
HTTP: stream_res=5

HTTP 枚举 0、1、2 分别表示 4K、4KUHD、27K,不能写成 0 = 1080P。高分辨率和高帧率组合须由目标型号的录像档位支持。第一次联调使用 720P / 30 fps;需要 25 fps 时显式写入 fmcam.conf,并核对状态返回。

当前独立 HTTP stream_framerate 入口会拒绝 24、25、48、100、120、200、240;50、60 还受分辨率档位限制。video_framerate 的 CGI 转换将 25 映射到 30、50 映射到 60。不要仅根据返回成功推断实际帧率。

常用控制参数

参数 三个型号的通用写法
dzoom 0~10;0 表示关闭数字变焦。
mic_sensitivity 0~5;按相机实际音量需求选择档位。
led / stamp / thm 0:关闭;1:开启。
exposure 0、1、2、3、4 分别对应曝光补偿 0、+1、+2、-1、-2。
filter 0:标准;1:鲜艳;2:低照度。
fov 90、115、140;实际生效还受录像档位约束。
language 0:英文;1:中文。

三型号共用的 RTSP 起步配置

在 SD 卡根目录创建 fmcam.conf,并将公司示例 Wi-Fi 名称与密码替换为实际网络信息。

stream_type=rtsp
router_ssid=DRIFTSEE_WIFI
router_password=CHANGE_ME
stream_resolution=720P
stream_framerate=30
stream_bitrate=2000000
stream_audio=1

通话音源与改参顺序

SDK Demo 的手机麦克风链路输出 AAC-LC、16 kHz、双声道;外部 RTSP 音源按同一配置准备,并确保相机可以访问。相机来向声音以 RTSP 中实际音轨为准。

修改参数前,先结束通话并停止预览、推流和录像;完成参数设置后读取 get_camera_status,再恢复预览或通话。HTTP Status=1 表示指令已受理,最终参数和两路音频仍需分别确认。

Drift 相机提供开放 API,便于开发者构建定制应用。本文介绍如何获取相机实时视频,以及如何远程控制和配置相机。

应用可通过 RTSP 协议获取 Drift 相机的实时视频。完成配置后,相机作为视频流服务器,电脑或手机上的应用通过 RTSP 地址拉取视频。

除了作为 RTSP 服务器,Drift 相机还可将实时视频推送至云端或局域网内的 RTMP 服务器。

Wi-Fi 配网

Drift 相机以 Station(客户端)模式接入 Wi-Fi 路由器或手机个人热点,应用通过同一网络访问相机。

相机支持两种配网方式:通过配置文件填写 Wi-Fi 和视频流参数,或扫描包含配网信息的二维码。

1.1 配置文件

创建名为 fmcam.conf 的文本文件,按实际网络填写以下内容,并保存至相机存储卡根目录。请确认文件扩展名为 .conf。

router_ssid=xxxxxx
router_password=12345678
stream_type=rtsp
stream_resolution=720P
stream_bitrate=2000000
stream_framerate=30

例如:

说明:

a)将 router_ssid 和 router_password 分别替换为 Wi-Fi 路由器或手机热点的名称与密码。

b)视频流分辨率可设为 480P、720P 或 1080P。码率 2000000 对应 2 Mbps;帧率可选 30 或 60。各型号的推荐配置如下:

  • XL Pro:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。
  • X5:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。
  • X5 Mini:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。

c)存储卡中存在 fmcam.conf 时,相机每次开机都会自动启用 Wi-Fi,并作为视频流服务器运行。如需停用,删除该文件即可恢复常规使用。相机连接 Wi-Fi 后,也可按 Wi-Fi 按钮断开连接。

1.2 扫描二维码

应用与相机接入同一网络后即可通信。应用生成包含路由器名称和密码的二维码,相机扫码获取信息后自动连接路由器。

二维码内容格式:

17|router_ssid|router_password|stream_type

字段说明:

  • 17:固定值,表示二维码类型。
  • router_ssid:Wi-Fi 名称,不可为空。
  • router_password:Wi-Fi 密码,可以为空。
  • stream_type:视频流类型,仅支持 RTSP。

例如:

可使用二维码生成工具(例如 https://www.qr-code-generator.com/)将上述文本生成二维码。开发自己的应用时,可参考以下开源项目。

ZXing(“Zebra Crossing”):适用于 Java 和 Android 的条码扫描库。

https://github.com/zxing/zxing

获取相机 IP 地址

相机连接 Wi-Fi 后,会向同一网络内的手机或电脑发送 UDP 广播,广播包含建立连接所需的信息。应用获取相机地址后,即可发送 HTTP 命令进行控制。

UDP 广播端口为 5555,报文内容格式如下:

5|cam_serial|cam_model|phone_uuid|rtmp_status

字段说明:

  • 5:固定值,表示广播类型。
  • cam_serial:相机序列号。
  • cam_model:相机型号。
  • phone_uuid:可在 fmcam.conf 中通过 phone_uuid=****** 设置,最多 64 个字符;未设置时此字段为空。
  • rtmp_status:相机状态,默认值 N 表示常规状态,当前未进行直播。

注意:可从 UDP 报文头中获取发送端的相机 IP 地址。

例如:

"5|86QHPFKVRIR0AB36|X5||N"

  • 86QHPFKVRIR0AB36 为相机序列号。
  • X5 为相机型号。
  • phone_uuid 未设置。
  • N 表示相机处于常规状态。

获取相机实时视频

连接建立后,应用可使用 VLC、ijk 或 vitamio 等播放器拉取相机实时视频。RTSP 地址格式为 rtsp://相机IP/live。

1)在电脑上安装 VLC 播放器。

2)获取相机 IP 地址,例如 192.168.4.148。

3)打开 VLC,选择“媒体 → 打开网络串流”,在地址栏中输入 rtsp://192.168.4.148/live。

4)点击“播放”,即可查看相机实时画面。

将实时视频推送至 RTMP 服务器

连接建立后,应用可通过以下 HTTP 接口控制相机向 RTMP 服务器推流。先获取相机 IP 地址(例如 192.168.4.148),再发送开始或停止直播命令。

4.1 启动 RTMP 直播

http://192.168.4.148/cgi-bin/foream_remote_control?start_rtmp_with_param=192.168.3.133:1935/live/5&stream_res=720P&stream_bitrate=2000000

其中,192.168.3.133:1935/live/5 表示 RTMP 服务器地址,省略 rtmp:// 前缀。

该命令也可同时设置直播分辨率和码率。

注意:若 RTMP 地址包含字符【&】,请将其替换为【***】。

例如:

原 RTMP 地址:

"rtmp://wxalivepush.weixin.qq.com/live/wx3059da5fb34ccef3-4?txSecret=bc91766cea0589c907c764cdf41d0047&txTime=629f7600"

替换后的地址:

"rtmp://wxalivepush.weixin.qq.com/live/wx3059da5fb34ccef3-4?txSecret=bc91766cea0589c907c764cdf41d0047***txTime=629f7600"

4.2 停止直播

http://192.168.4.148/cgi-bin/foream_remote_control?stop_rtmp

控制相机拉取 RTSP 音频

Drift 相机既可提供 RTSP 视频流,也可从远程 RTSP 服务器拉取并播放音频。音频格式须为 AAC、双声道、16 kHz 采样率。

1)设置相机的 rtsp_url 音频地址

http://192.168.5.181/cgi-bin/foream_remote_control?rtsp_url=rtsp://192.168.5.53/audio_test_file.aac

2)设置 RTSP 音频地址并开始播放

http://192.168.5.181/cgi-bin/foream_remote_control?start_rtsp=rtsp://192.168.5.53/audio_test_file.aac

3)停止播放音频流

http://192.168.5.181/cgi-bin/foream_remote_control?stop_rtsp

注意:上述示例的相机 IP 为 192.168.5.181,使用时请替换为实际相机 IP。

播放网络或存储卡中的音频文件

Drift 相机还可播放远程服务器或存储卡上的音频文件,音频格式须为 AAC、双声道、16 kHz 采样率。

1)播放相机存储卡中的音频文件

http://192.168.5.181/cgi-bin/foream_remote_control?play_audio_file=/tmp/SD0/audio_test_file.aac

将音频文件(如 audio_test_file.aac)放入相机 Micro SD 卡,发送上述命令即可播放。

audio_test_file.aac 必须采用 AAC 编码、双声道和 16 kHz 采样率。

示例音频地址:

http://www.driftlife.co/download/audio_test_file.aac

2)播放网络音频文件

http://192.168.5.181/cgi-bin/foream_remote_control?play_audio_url=http://www.driftlife.co/download/audio_test_file.aac&file_size=23316

此接口需要两个参数:音频文件的下载地址,以及文件大小。

    

相机控制

连接建立后,应用可通过 HTTP 接口控制相机。先获取相机 IP 地址(例如 192.168.4.148),再发送以下命令。

7.1 基本操作接口

1)数字变焦

http://192.168.4.148/cgi-bin/foream_remote_control?dzoom=1

dzoom 的取值范围为 0~10,0 表示不启用数字变焦。

2)开始录像

http://192.168.4.148/cgi-bin/foream_remote_control?start_record

3)停止录像

http://192.168.4.148/cgi-bin/foream_remote_control?stop_record

4)切换至录像模式

http://192.168.4.148/cgi-bin/foream_remote_control?switch_video_mode

5)切换至拍照模式

http://192.168.4.148/cgi-bin/foream_remote_control?switch_photo_mode

6)拍照

拍照前请确认相机处于拍照模式;可先发送 switch_photo_mode 命令切换模式。

http://192.168.4.148/cgi-bin/foream_remote_control?take_photo

7)恢复设置

http://192.168.4.148/cgi-bin/foream_remote_control?reset_setting

8)重启相机

http://192.168.4.148/cgi-bin/foream_remote_control?reboot

9)关闭相机

http://192.168.4.148/cgi-bin/foream_remote_control?power_off

11)指定参数录像

http://192.168.4.148/cgi-bin/foream_remote_control?record_with_param=PriName&sec_id=SecName

该接口可为录像文件设置自定义名称。PriName 和 SecName 仅支持字母和数字,生成的名称格式为 Priname_Secname。可通过 mediaInfo 接口查询此名称。

例如:

依次向相机发送以下命令:

http://192.168.4.148/cgi-bin/foream_remote_control?record_with_param=T002&sec_id=L0000001
http://192.168.4.148/cgi-bin/foream_remote_control?stop_record
http://192.168.5.62/cgi-bin/foream_remote_control?mediaInfo

相机返回的文件信息示例:

{
  "path": "100MEDIA\\VID00024.MP4",
  "name": "T002_L0000001",
  "time": "2024-01-01 00:38:55",
  "size": "69512330"
}

7.2 相机参数设置

1)设置 LED 指示灯

http://192.168.4.148/cgi-bin/foream_remote_control?led=1

取值说明:1 为开启,0 为关闭。

2)设置曝光补偿

http://192.168.4.148/cgi-bin/foream_remote_control?exposure=1

取值说明:0 对应 0,1 对应 +1,2 对应 +2,3 对应 -1,4 对应 -2。

3)设置滤镜

http://192.168.4.148/cgi-bin/foream_remote_control?filter=1

取值说明:0 为标准,1 为鲜艳,2 为低照度。

4)设置麦克风灵敏度

http://192.168.4.148/cgi-bin/foream_remote_control?mic_sensitivity=1

取值范围为 0~5,分别对应各档麦克风灵敏度。

5)设置日期时间水印

http://192.168.4.148/cgi-bin/foream_remote_control?stamp=1

取值说明:0 为关闭日期时间水印,1 为开启。

6)设置视场角

http://192.168.4.148/cgi-bin/foream_remote_control?fov=140

可选值为 140、115、90。

7)设置缩略图文件

http://192.168.4.148/cgi-bin/foream_remote_control?thm=1

可选值为 0 或 1。

8)设置相机语言

http://192.168.4.148/cgi-bin/foream_remote_control?language=1

取值说明:0 为英文,1 为中文。

9)设置相机时间

http://192.168.4.148/cgi-bin/foream_remote_control?set_time=2021-03-01_09:35:00

此示例将相机时间设置为 2021/3/1 9:35。

7.3 实时视频参数

先结束预览、推流与录像,再修改分辨率和帧率。三个型号的码率单位见本页型号参数表。

1)720P 分辨率(1080P 用 3,WVGA 用 5)

http://CAMERA_IP/cgi-bin/foream_remote_control?stream_res=4

2)2 Mbps 码率:XL Pro

http://CAMERA_IP/cgi-bin/foream_remote_control?stream_bitrate=250000

2)2 Mbps 码率:X5 / X5 Mini

http://CAMERA_IP/cgi-bin/foream_remote_control?stream_bitrate=2000000

3)30 帧/秒

http://CAMERA_IP/cgi-bin/foream_remote_control?stream_framerate=30

7.4 录像参数

在停止录像后设置。video_res 与 stream_res 共用分辨率数值枚举;分辨率与帧率组合须由目标型号和固件支持。

1)1080P 录像分辨率

http://CAMERA_IP/cgi-bin/foream_remote_control?video_res=3

2)4 Mbps 录像码率:三个型号均填写 500000 Byte/s。

http://CAMERA_IP/cgi-bin/foream_remote_control?video_bitrate=500000

3)30 帧/秒;设置后读取状态确认实际档位。

http://CAMERA_IP/cgi-bin/foream_remote_control?video_framerate=30

7.5 相机状态

1)获取 XL Pro、X5、X5 Mini 相机当前状态

http://192.168.4.148/cgi-bin/foream_remote_control?get_camera_status

相机以 XML 格式返回状态,示例如下:

<Response>
  <Status>1</Status>
  <Cam_Status>
    <camera_status>
      <capture_mode>0</capture_mode>
      <battery>100</battery>
      <sd_free>15804576</sd_free>
      <sd_total>31166464</sd_total>
      <rec_time>0</rec_time>
      <fw_ver>1127</fw_ver>
      <model_name>X5_Mini</model_name>
      <time>2024-05-10 12:12:54</time>
    </camera_status>
    <video_setting>
      <res>2</res>
      <framerate>30</framerate>
      <bitrate>2000000</bitrate>
      <quality>0</quality>
    </video_setting>
    <stream_setting>
      <stream_res>0</stream_res>
      <stream_framerate>24</stream_framerate>
      <stream_bitrate>2000000</stream_bitrate>
    </stream_setting>
    <camera_setting>
      <dzoom>0</dzoom>
      <filter>0</filter>
      <exposure>0</exposure>
      <mic>5</mic>
      <led>1</led>
      <fov>140</fov>
      <thm>0</thm>
      <stamp>0</stamp>
      <eis>0</eis>
      <speaker_volume>6</speaker_volume>
      <iso>0</iso>
      <voice>2</voice>
      <language>1</language>
      <cardv>0</cardv>
      <cardv_interval>60</cardv_interval>
      <video_timelapse>0</video_timelapse>
      <video_timelapse_interval>10</video_timelapse_interval>
      <wifi_frequency>0</wifi_frequency>
    </camera_setting>
  </Cam_Status>
  <websocket>0</websocket>
</Response>

主要状态字段:

字段 说明
Status 1 表示成功。
capture_mode 0:录像;1:拍照;2:延时摄影;3:连拍。X5 Mini 支持录像和拍照。
battery 剩余电量,单位为百分比。
sd_free SD 卡剩余容量,单位为 KB。
sd_total SD 卡总容量,单位为 KB。
rec_time 0 表示空闲;其他值表示当前录像时长。
fw_ver 固件版本。
model_name 相机型号。
time 相机日期与时间。

7.6 文件操作

1)列出 SD 卡媒体文件夹

http://192.168.4.148/cgi-bin/foream_remote_control?list_folders=/tmp/SD0/DCIM

列出相机 SD 卡 DCIM 目录下的所有媒体文件夹。

<Response>
  <Folders>
    {"Path":"100MEDIA"},
  </Folders>
  <Amount>1</Amount>
</Response>

2)列出 SD 卡媒体文件

http://192.168.4.148/cgi-bin/foream_remote_control?list_files=/tmp/SD0/DCIM

列出 SD 卡上的所有媒体文件。

<Response>
  <Files>
    {"Path":"PH000011.JPG","CreateTime":"Apr 26 19:12:50 2024","Size":2034256,"Thumb":1},
    {"Path":"PH000012.JPG","CreateTime":"Apr 26 19:12:54 2024","Size":1632571,"Thumb":1},
    {"Path":"VID00013.MP4","CreateTime":"Jan 01 00:38:54 2024","Size":69512330,"Thumb":1},
  </Files>
  <Amount>3</Amount>
</Response>

注意:

预览或下载媒体文件时,请使用以下地址:

http://192.168.4.148/DCIM/100MEDIA/VID00001.MP4
http://192.168.4.148/DCIM/100MEDIA/VID00002.MP4

3)列出自定义名称的录像文件

http://192.168.4.148/cgi-bin/foream_remote_control?mediaInfo

列出 SD 卡上所有设置了自定义名称的录像文件。

1

<Response>
  <Status>1</Status>
  <Files>
    {
      "files": [
        {
          "path": "DCIM\\100MEDIA\\VID00001.MP4",
          "name": "priname_name123",
          "time": "2022-09-12 14:22:40",
          "size": "86620487"
        },
        {
          "path": "DCIM\\100MEDIA\\VID00002.MP4",
          "name": "priname_name456",
          "time": "2022-09-12 15:22:40",
          "size": "85420487"
        }
      ]
    }
  </Files>
</Response>

4)删除 SD 卡媒体文件

http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_file=100MEDIA/VID00003.MP4

注意:相机正在录像时,不可调用此接口。

5)批量删除 SD 卡媒体文件

http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_multfiles=3|100MEDIA/VID00003.MP4|100MEDIA/VID00004.MP4|100MEDIA/VID00005.MP4

文件之间使用字符“|”分隔,第一项必须填写文件数量,最多为 40 个。相机正在录像时,不可调用此接口。

注意:iOS 应用需将字符【|】替换为【*%7C*】,例如:

http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_multfiles=3*%7C*100MEDIA/VID00003.MP4*%7C*100MEDIA/VID00004.MP4*%7C*100MEDIA/VID00005.MP4