Skip to content

Ocyss/srs-auth / .agents/skills/internal-docs-for-srs

internal-docs-for-srs

Flagged

Route SRS and Oryx tasks to the smallest relevant set of trusted project documentation and maintain the project documentation bundled with this skill. Use whenever support or development work requires locating, choosing, reading, creating, updating, or reviewing SRS documentation, or whenever Oryx work requires project documentation for deployment, streaming, authentication, recording to local or S3-compatible storage, restreaming, virtual live, camera, transcoding, HTTPS, APIs, callbacks, AI features, or development. Includes the C++ media server documentation, Oryx project documentation, website pages, changelog, executable API examples, and next-generation Go server and performance documentation.

FileKindSize
SKILL.mdskill md12.2 KB
references/cpp-docs/doc/dvr.mdmarkdown11.3 KB
references/cpp-docs/doc/edge.mdmarkdown6.0 KB
references/cpp-docs/doc/exporter.mdmarkdown5.3 KB
references/cpp-docs/doc/ffmpeg.mdmarkdown13.1 KB
references/cpp-docs/doc/flv.mdmarkdown13.3 KB
references/cpp-docs/doc/forward.mdmarkdown8.3 KB
references/cpp-docs/doc/gb28181.mdmarkdown2.2 KB
references/cpp-docs/doc/getting-started-ai.mdmarkdown5.9 KB
references/cpp-docs/doc/getting-started-build.mdmarkdown5.3 KB
references/cpp-docs/doc/getting-started-cdk.mdmarkdown264 B
references/cpp-docs/doc/getting-started.mdmarkdown6.7 KB
references/cpp-docs/doc/hevc.mdmarkdown18.4 KB
references/cpp-docs/doc/hls.mdmarkdown34.8 KB
references/cpp-docs/doc/http-api.mdmarkdown18.4 KB
references/cpp-docs/doc/http-callback.mdmarkdown16.5 KB
references/cpp-docs/doc/http-server.mdmarkdown9.5 KB
references/cpp-docs/doc/ingest.mdmarkdown3.3 KB
references/cpp-docs/doc/introduction.mdmarkdown11.4 KB
references/cpp-docs/doc/low-latency.mdmarkdown6.5 KB
references/cpp-docs/doc/nginx-for-hls.mdmarkdown10.8 KB
references/cpp-docs/doc/origin-cluster.mdmarkdown18.5 KB
references/cpp-docs/doc/performance.mdmarkdown26.8 KB
references/cpp-docs/doc/resource.mdmarkdown3.4 KB
references/cpp-docs/doc/rtmp.mdmarkdown18.6 KB
references/cpp-docs/doc/rtsp.mdmarkdown7.3 KB
references/cpp-docs/doc/security.mdmarkdown2.0 KB
references/cpp-docs/doc/snapshot.mdmarkdown3.6 KB
references/cpp-docs/doc/srt.mdmarkdown29.1 KB
references/cpp-docs/doc/webrtc.mdmarkdown34.0 KB
references/cpp-docs/pages/faq-server-en.mdmarkdown31.0 KB
references/cpp-docs/pages/license-en.mdmarkdown6.8 KB
references/cpp-docs/pages/product-en.mdmarkdown25.7 KB
references/cpp-docs/pages/security-advisories-en.mdmarkdown1.4 KB
references/oryx/2022-04-09-Oryx-Tutorial.mdmarkdown14.2 KB
references/oryx/2022-04-12-Oryx-HTTPS.mdmarkdown5.0 KB
references/oryx/2022-04-15-Oryx-WordPress-Plugin.mdmarkdown4.9 KB
references/oryx/2022-04-29-BT-aaPanel.mdmarkdown5.6 KB
references/oryx/2023-08-29-Oryx-Ensuring-Authentication-for-Live-Streaming-Publishing.mdmarkdown6.2 KB
references/oryx/2023-09-09-Oryx-Multi-Platform-Streaming.mdmarkdown4.9 KB
references/oryx/2023-09-10-Oryx-Record-Live-Streaming.mdmarkdown4.5 KB
references/oryx/2023-09-11-Oryx-Virtual-Live-Events.mdmarkdown6.0 KB
references/oryx/2023-10-11-Oryx-Stream-IP-Camera-Events.mdmarkdown5.3 KB
references/oryx/2023-10-21-Oryx-Live-Transcoding.mdmarkdown5.4 KB
references/oryx/2023-11-28-Oryx-Live-Streams-Transcription.mdmarkdown5.4 KB
references/oryx/2023-12-12-Oryx-OBS-WHIP-Service.mdmarkdown4.5 KB
references/oryx/2024-01-31-Browser-Voice-Driven-GPT.mdmarkdown9.5 KB
references/oryx/2024-02-21-Dubbing-Translating.mdmarkdown5.0 KB
references/oryx/2024-05-20-OCR-Video-Streams.mdmarkdown4.3 KB
references/oryx/faq-oryx-en.mdmarkdown37.0 KB
references/oryx/getting-started-oryx.mdmarkdown15.9 KB
references/perf/proxy-whep.mdmarkdown5.4 KB
references/proxy/features.mdmarkdown9.3 KB
references/proxy/proxy-design.mdmarkdown2.8 KB
references/proxy/proxy-load-balancer.mdmarkdown5.8 KB
references/proxy/proxy-origin-cluster.mdmarkdown5.7 KB
references/proxy/proxy-protocol.mdmarkdown5.8 KB
references/proxy/proxy-usage.mdmarkdown2.7 KB

references/cpp-docs/doc/http-callback.md

View on GitHub
---
title: HTTP Callback
sidebar_label: HTTP Callback
hide_title: false
hide_table_of_contents: false
---

# HTTPCallback

SRS supports HTTP callback to extends SRS. The workflow is:

```text
+--------+     +--------+                    +-----------------------+
| FFmpeg |-->--+  SRS   |--HTTP-Callback-->--+  Your Business Server |
+--------+     +--------+                    +-----------------------+
```

When FFmpeg/OBS publish or play a stream to SRS, SRS will call your business server to notify the event.

## Usage

First, run SRS with HTTP callback enabled:

```bash
./objs/srs -c conf/http.hooks.callback.conf
```

Start the demo HTTP callback server, which is your business server:

```bash
go run research/api-server/server.go
```

Publish a stream to SRS, with the params:

```bash
ffmpeg -re -i doc/source.flv -c copy -f flv rtmp://localhost/live/livestream?k=v
```

Your business server will got the HTTP event:

```text
Got action=on_publish, client_id=3y1tcaw2, ip=127.0.0.1, vhost=__defaultVhost__, stream=livestream, param=?k=v
```

Note that the `k=v` can be used for authentication, for token authentication based on HTTP callbacks,
read [Token Authentication](./drm.md#token-authentication)

## Compile

SRS always enable http callbacks.

For more information, read [Build](./install.md)

## Configuring SRS

An example [conf/http.hooks.callback.conf](https://github.com/ossrs/srs/blob/develop/trunk/conf/http.hooks.callback.conf) 
is available, demonstrating the configuration of common callback events for direct use.

The config for HTTP hooks is:

```bash
vhost your_vhost {
    http_hooks {
        # whether the http hooks enable.
        # default off.
        enabled         on;
        # when client(encoder) publish to vhost/app/stream, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_publish",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy", "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        # support multiple api hooks, format:
        #       on_publish http://xxx/api0 http://xxx/api1 http://xxx/apiN
        # @remark For SRS4, the HTTPS url is supported, for example:
        #       on_publish https://xxx/api0 https://xxx/api1 https://xxx/apiN
        on_publish      http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams;
        # when client(encoder) stop publish to vhost/app/stream, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_unpublish",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy", "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        # support multiple api hooks, format:
        #       on_unpublish http://xxx/api0 http://xxx/api1 http://xxx/apiN
        # @remark For SRS4, the HTTPS url is supported, for example:
        #       on_unpublish https://xxx/api0 https://xxx/api1 https://xxx/apiN
        on_unpublish    http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams;
        # when client start to play vhost/app/stream, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_play",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy",
        #           "pageUrl": "http://www.test.com/live.html", "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        # support multiple api hooks, format:
        #       on_play http://xxx/api0 http://xxx/api1 http://xxx/apiN
        # @remark For SRS4, the HTTPS url is supported, for example:
        #       on_play https://xxx/api0 https://xxx/api1 https://xxx/apiN
        on_play         http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions;
        # when client stop to play vhost/app/stream, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_stop",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy", "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        # support multiple api hooks, format:
        #       on_stop http://xxx/api0 http://xxx/api1 http://xxx/apiN
        # @remark For SRS4, the HTTPS url is supported, for example:
        #       on_stop https://xxx/api0 https://xxx/api1 https://xxx/apiN
        on_stop         http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions;
        # when srs reap a dvr file, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_dvr",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy",
        #           "cwd": "/usr/local/srs",
        #           "file": "./objs/nginx/html/live/livestream.1420254068776.flv", "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        on_dvr          http://127.0.0.1:8085/api/v1/dvrs http://localhost:8085/api/v1/dvrs;
        # when srs reap a ts file of hls, call the hook,
        # the request in the POST data string is a object encode by json:
        #       {
        #           "action": "on_hls",
        #           "client_id": "9308h583",
        #           "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live",
        #           "stream": "livestream", "param":"?token=xxx&salt=yyy",
        #           "duration": 9.36, // in seconds
        #           "cwd": "/usr/local/srs",
        #           "file": "./objs/nginx/html/live/livestream/2015-04-23/01/476584165.ts",
        #           "url": "live/livestream/2015-04-23/01/476584165.ts",
        #           "m3u8": "./objs/nginx/html/live/livestream/live.m3u8",
        #           "m3u8_url": "live/livestream/live.m3u8",
        #           "seq_no": 100, "server_id": "vid-werty",
        #           "stream_url": "video.test.com/live/livestream", "stream_id": "vid-124q9y3"
        #       }
        # if valid, the hook must return HTTP code 200(Status OK) and response
        # an int value specifies the error code(0 corresponding to success):
        #       0
        on_hls          http://127.0.0.1:8085/api/v1/hls http://localhost:8085/api/v1/hls;
        # when srs reap a ts file of hls, call this hook,
        # used to push file to cdn network, by get the ts file from cdn network.
        # so we use HTTP GET and use the variable following:
        #       [server_id], replace with the server_id
        #       [app], replace with the app.
        #       [stream], replace with the stream.
        #       [param], replace with the param.
        #       [ts_url], replace with the ts url.
        # ignore any return data of server.
        # @remark random select a url to report, not report all.
        on_hls_notify   http://127.0.0.1:8085/api/v1/hls/[server_id]/[app]/[stream]/[ts_url][param];
    }
}
```

Description about some fields:

* `stream_url`: The stream identify without extension, such as `/live/livestream`.
* `stream_id`: The id of stream, by which you can query the stream information.

> Note: The callbacks for streaming are `on_publish` and `on_unpublish`, while the callbacks for playback are `on_play` and `on_stop`.

> Note: These callbacks also apply to WebRTC. WHIP publishing invokes
> `on_publish`, and WHEP playback invokes `on_play`. The callbacks can authorize
> WHIP and WHEP by themselves because RTC Bearer authentication is disabled by
> default. When combined with [Bearer authentication](./http-api.md#bearer-token-authentication),
> enable `rtc_bearer_enabled`; the WHIP or WHEP request must then pass Bearer
> authentication before SRS invokes the callback.

> Note: Before SRS 4, there were `on_connect` and `on_close`, which are events defined by RTMP and only applicable to RTMP streams. These events overlap with streaming and playback events, so their use is not recommended.

> Note: You can refer to the hooks.callback.vhost.com example in the conf/full.conf configuration file.

## Protocol

The detail protocol, for example, `on_publish`:

```text
POST /api/v1/streams HTTP/1.1
Content-Type: application-json

Body:
{
  "server_id": "vid-0xk989d",
  "action": "on_publish",
  "client_id": "341w361a",
  "ip": "127.0.0.1",
  "vhost": "__defaultVhost__",
  "app": "live",
  "tcUrl": "rtmp://127.0.0.1:1935/live?vhost=__defaultVhost__",
  "stream": "livestream",
  "param": "",
  "stream_url": "video.test.com/live/livestream",
  "stream_id": "vid-124q9y3"
}
```

> Note: You can use wireshark or tcpdump to verify it.

## Heartbeat

SRS will send heartbeat to the HTTP callback server. This allows you to monitor the health of SRS server.
Enable this feature by:

```bash
# heartbeat to api server
# @remark, the ip report to server, is retrieve from system stat,
#       which need the config item stats.network.
heartbeat {
    # whether heartbeat is enabled.
    # Overwrite by env SRS_HEARTBEAT_ENABLED
    # default: off
    enabled off;
    # the interval seconds for heartbeat,
    # recommend 0.3,0.6,0.9,1.2,1.5,1.8,2.1,2.4,2.7,3,...,6,9,12,....
    # Overwrite by env SRS_HEARTBEAT_INTERVAL
    # default: 9.9
    interval 9.3;
    # when startup, srs will heartbeat to this api.
    # @remark: must be a restful http api url, where SRS will POST with following data:
    #   {
    #       "device_id": "my-srs-device",
    #       "ip": "192.168.1.100"
    #   }
    # Overwrite by env SRS_HEARTBEAT_URL
    # default: http://127.0.0.1:8085/api/v1/servers
    url http://127.0.0.1:8085/api/v1/servers;
    # the id of device.
    # Overwrite by env SRS_HEARTBEAT_DEVICE_ID
    device_id       "my-srs-device";
    # whether report with summaries
    # if on, put /api/v1/summaries to the request data:
    #   {
    #       "summaries": summaries object.
    #   }
    # @remark: optional config.
    # Overwrite by env SRS_HEARTBEAT_SUMMARIES
    # default: off
    summaries off;
    # Optional authentication for the heartbeat request.
    auth {
        # Overwrite by env SRS_HEARTBEAT_AUTH_ENABLED
        # default: off
        enabled off;
        # Overwrite by env SRS_HEARTBEAT_AUTH_TYPE
        # only bearer is supported
        type bearer;
        # Overwrite by env SRS_HEARTBEAT_AUTH_TOKEN
        token proxy-registration-token;
    }
}
```

By enable the `summaries`, you can get the SRS server states, such as `self.pid` and `self.srs_uptime`, so you
can use this to determine whether SRS restarted.

> Note: About fileds of `summaries`, see [HTTP API: summaries](./http-api.md#summaries) for details.

## Go Example

Write Go code to handle SRS callback, for example, handling `on_publish`:

```go
http.HandleFunc("/api/v1/streams", func(w http.ResponseWriter, r *http.Request) {
    b, err := ioutil.ReadAll(r.Body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }

    fmt.Println(string(b))

    res, err := json.Marshal(struct {
        Code int `json:"code"`
        Message string `json:"msg"`
    }{
        0, "OK",
    })
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
    w.Write(res)
})

_ = http.ListenAndServe(":8085", nil)
```

## Nodejs Koa Example

Write Nodejs/Koa code to handle SRS callback, for example, handling `on_publish`:

```js
const Router = require('koa-router');
const router = new Router();

router.all('/api/v1/streams', async (ctx) => {
  console.log(ctx.request.body);

  ctx.body = {code: 0, msg: 'OK'};
});
```

## PHP Example

Write PHP code to handle SRS callback, for example, handling `on_publish`:

```php
$body = json_decode(file_get_contents('php://input'));
printf($body);

echo json_encode(array("code"=>0, "msg"=>"OK"));
```

## HTTP Callback Events

SRS can call HTTP callbacks for events:

* `on_publish`: When a client publishes a stream, for example, using flash or FMLE to publish a stream to the server. 
* `on_unpublish`: When a client stops publishing a stream. 
* `on_play`: When a client starts playing a stream. 
* `on_stop`: When a client stops playback. 
* `on_dvr`: When reap a DVR file.
* `on_hls`: When reap a HLS file.

For events `on_publish`和`on_play`:
* Return Code: SRS requires that the response is an int indicating the error, 0 is success.

Notes:
* Event: When this event occurs, call back to the specified HTTP URL.
* HTTP URL: Can be multiple URLs, split by spaces, SRS will notify all one by one.
* Data: SRS will POST the data to specified HTTP API.

SRS will disconnect the connection when the response is not 0, or HTTP status is not 200.

## SRS HTTP Callback Server

SRS provides a default HTTP callback server, using golang native http framework.

To start it: 

```bash
cd research/api-server && go run server.go 8085
```

```bash
#2023/01/18 22:57:40.835254 server.go:572: api server listen at port:8085, static_dir:/Users/panda/srs/trunk/static-dir
#2023/01/18 22:57:40.835600 server.go:836: start listen on::8085
```

> Remark: For SRS4, the HTTP/HTTPS url is supported, see [#1657](https://github.com/ossrs/srs/issues/1657#issuecomment-720889906).

## HTTPS Callback

HTTPS Callback is supported by SRS4, only change the callback URL from `http://` to `https://`, for example:

```
vhost your_vhost {
    http_hooks {
        enabled         on;
        on_publish      https://127.0.0.1:8085/api/v1/streams;
        on_unpublish    https://127.0.0.1:8085/api/v1/streams;
        on_play         https://127.0.0.1:8085/api/v1/sessions;
        on_stop         https://127.0.0.1:8085/api/v1/sessions;
        on_dvr          https://127.0.0.1:8085/api/v1/dvrs;
        on_hls          https://127.0.0.1:8085/api/v1/hls;
        on_hls_notify   https://127.0.0.1:8085/api/v1/hls/[app]/[stream]/[ts_url][param];
    }
}
```

## Response

If success, you must response `something` to identify the success, or SRS will reject the client, which enable you to reject the illegal client, please read [Callback Error Code](./http-api.md#error-code). 

> Note: The `on_publish` callback also could be used as advanced security, to `allow` or `deny` a client by its IP, or token in request url, or any other information of client.

Where `something` means:

* HTTP/200, which is HTTP success.
* `AND` response and int value 0, or JSON object with field code 0.

Like this:

```
HTTP/1.1 200 OK
Content-Length: 1
0
```

OR:

```
HTTP/1.1 200 OK
Content-Length: 11
{"code": 0}
```

You could run the example HTTP callback server by:

```
cd srs/trunk/research/api-server && go run server.go 8085
```

And you will finger out what's the `right` response.

## Snapshot

The HttpCallback can used to snapshot, please read [snapshot](./snapshot.md#httpcallback)

Winlin 2015.1

![](https://ossrs.io/gif/v1/sls.gif?site=ossrs.io&path=/lts/doc/en/v7/http-callback)
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall