实时播放示例 (同步 HTTP API)

推荐作为首次集成入口。 本示例用最少的概念（登录 → 打开 → 播放 → 保活 → 关闭）演示单路 HTTP-FLV 实时音视频，采用 同步打开 模式（ 接口返回时媒体通常已就绪，无需订阅 WebSocket 通知）。

项目	说明
示例页面	live-example-1（Chrome / Firefox / Edge）
示例代码	live-example-1.zip
API 基址	https://wx.gratour.info:7200/v1
依赖库	axios、flv.js
测试终端	真实终端，或演示站模拟终端 8888000001

相关文档：应用指南概览 · 会话与 token · 打开实时音视频

适合场景

• 第一次对接 GT-Streaming，希望 逻辑最简单
• 单路或少量实时播放，可接受打开接口 阻塞等待 终端推流
• 不需要 STOMP WebSocket，客户端代码尽量短

若需 多路并发 或打开接口 立即返回，请参阅 实时播放示例 (异步 HTTP API)。

同步 vs 异步（本示例为何选同步）

	同步（本示例）	异步（example-2）
请求参数	不传 async 或 async: false	async: true
接口返回时机	终端推流就绪或失败后才返回	分配 reqId 后立即返回
ready	成功时通常为 true	常为 false，需等通知
WebSocket	不需要	必须 订阅 /user/{token}/queue/strm
复杂度	低	较高

详见 异步与同步模式。

整体流程

1. 终端经网关上线
2. POST /login              → 获得 authToken
3. POST /strm/live/open     → 等待终端推流（同步），返回 reqId、playUrl
4. flv.js 加载 playUrl      → 开始播放
5. 每 15 秒 POST /strm/keep_alive
6. 停止：销毁播放器 → POST /strm/close

准备工作

1. 终端上线

• 将 JT/T 1076 终端指向网关：wx.gratour.info:7510
• 若终端要求 ACC ON 才响应音视频，请接好 ACC 信号
• 在 演示站 确认终端已出现在「在线终端」列表

2. 浏览器

• 支持 MSE 的现代浏览器（不支持 iPhone Safari 播 FLV，需改用 HLS，见 example-3-live-hls）

步骤详解

步骤 1：登录

POST https://wx.gratour.info:7200/v1/login
Content-Type: application/json

{
  "userName": "admin",
  "password": "admin"
}

成功应答中 data[0].authToken 即会话 token，后续请求在请求头携带：

X-Auth-Token: <authToken>

API 说明：POST /login

步骤 2：打开实时音视频（同步）

POST https://wx.gratour.info:7200/v1/strm/live/open
Content-Type: application/json
X-Auth-Token: w3-73jH2TWq4cmYKGuCWMw

{
  "simNo": "8888000001",
  "channel": 1,
  "dataType": 0,
  "codeStream": 1,
  "proto": 0
}

常用参数：

参数	本示例值	含义
simNo	终端识别号	与网关登记一致
channel	1	逻辑通道号
dataType	0	音视频（1 仅视频，3 监听）
codeStream	1	子码流（0 主码流）
proto	0	客户端协议 FLV（HTTP-FLV）
async	省略	默认 false，即 同步模式

成功应答示例：

{
  "data": [{
    "reqId": "AbctuB9sSJe8bbBzv-yr9g",
    "ctrl": true,
    "playUrl": "https://...",
    "mediaTyp": "av",
    "ready": true
  }],
  "errCode": 0,
  "message": "OK."
}

应答字段（必记）：

字段	用途
reqId	保活、关闭时使用
playUrl	传给 flv.js 播放
mediaTyp	av / a / v，配置播放器音轨/视频轨
ready	同步模式下成功时一般为 true，可直接播放

常见失败： -27 终端不在线 · -5 超时 · -3 终端应答失败。见 常见问题与排错。

核心调用代码（示例 apiLiveOpen()）：

axios.post(apiUrlPrefix() + 'strm/live/open', {
    simNo: simNo(),
    channel: channelId(),
    dataType: dataType(),
    codeStream: codeStream(),
    proto: 0                    // FLV
}, {
    headers: { 'X-Auth-Token': token }
}).then(function (resp) {
    let data = apiCheck(resp).data[0];
    reqId = data.reqId;

    keepAliveTimer = setInterval(apiKeepAlive, 15000);
    createPlayerAndLoad(data.playUrl, data.mediaTyp);
});

步骤 3：保活（每 15 秒）

打开成功后 立即 启动定时器，否则服务端会因超时关闭请求。

POST https://wx.gratour.info:7200/v1/strm/keep_alive
Content-Type: application/json
X-Auth-Token: ...

{ "reqIds": ["AbctuB9sSJe8bbBzv-yr9g"] }

function apiKeepAlive() {
    axios.post(apiUrlPrefix() + 'strm/keep_alive', { reqIds: [reqId] }, {
        headers: { 'X-Auth-Token': token }
    }).then((resp) => {
        if (resp.data.errCode !== 0) {
            stop();   // 通道已关闭，清理播放器
        }
    });
}

API：POST /strm/keep_alive

步骤 4：播放

使用 flv.js 加载 playUrl（proto: 0 时为 HTTP-FLV 地址）：

function createPlayerAndLoad(url, mediaTyp) {
    let hasAudio = mediaTyp === 'av' || mediaTyp === 'a';
    let hasVideo = mediaTyp === 'av' || mediaTyp === 'v';

    flvPlayer = flvjs.createPlayer({
        type: 'flv', isLive: true, url, hasAudio, hasVideo
    }, { enableStashBuffer: false });

    flvPlayer.attachMediaElement(document.getElementById('vid'));
    flvPlayer.on('error', () => stop());
    flvPlayer.on('metadata_arrived', () => flvPlayer.play());
    flvPlayer.load();
}

步骤 5：停止播放

按顺序释放资源：

function stop() {
    clearInterval(keepAliveTimer);   // 1. 停止保活
    flvPlayer?.destroy();          // 2. 销毁播放器
    axios.post(apiUrlPrefix() + 'strm/close', { reqIds: [reqId] }, {
        headers: { 'X-Auth-Token': token }
    });                            // 3. 关闭媒体请求
    reqId = null;
}

也可通过 POST /strm/live/ctrl（ctrl: 0）关闭。未主动关闭时，保活超时后服务端会自动关闭。

同步模式的等待行为

同步打开时，POST /strm/live/open 会阻塞到：

• 终端开始推流 → 返回成功与 playUrl；或
• 判定终端不在线 / 推流失败 / 超时 → 返回错误码

部分终端响应较慢，接口可能等待 10 秒以上；界面应提示「正在打开…」，避免用户重复点击。

检查清单

集成完成后，请确认：

• 登录后所有 API 均带 X-Auth-Token
• 打开成功后保存了 reqId
• 15 秒保活定时器已启动，停止时已清除
• 播放器 error 回调中会停止保活并关闭请求
• 页面卸载或用户点「停止」时调用 strm/close

下一步

目标	文档
多路 / 非阻塞打开	example-2-live
iPhone Safari	example-3-live-hls
v4 推荐方式	ws-example-1-live
机制细节	音视频请求的生命周期
排错	常见问题与排错