Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Video Playback PubSub events. #583

Closed
wants to merge 1 commit into from
Closed

Video Playback PubSub events. #583

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 188 additions & 0 deletions PubSub/video-playback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
# Video Playback events over PubSub
Using the Twitch PubSub system (TPS), you can listen to video playback events occurring in a channel by subscribing to the video-playback event topic. For general information about TPS (including rate limits and best practices), check out the [Twitch PubSub System documentation](https://github.com/justintv/Twitch-API/tree/master/PubSub).

## Subscribing to a Video Playback topic
You can subscribe to a video playback topic for a channel by sending a simple JSON message. The topic has a specific format: `video-playback.<channel_id>`. When
subscribing to the video playback topic for a channel, you do not need to supply an authentication token.

In full, you would send a request that looks like the following:

```json
{
"type": "LISTEN",
"nonce": "...",
"data": {
"topics": ["video-playback.XXXXXXXX"],
}
}
```

After your initial request, you'll receive a response message with the error if applicable.
```json
{
"type": "RESPONSE",
"nonce": "...",
"error": "..."
}
```

The `nonce` field will match the request `nonce`. The `error` field will be an empty string if there is no error. If there is an error, it can be one of
ERR_BADMESSAGE, ERR_BADAUTH, ERR_SERVER, ERR_BADTOPIC.

## Receiving a Video Playback event message
When a message for your subscription is published, you will receive a message containing the applicable data. The message will look like the following:

```json
{
"type": "MESSAGE",
"data": {
"topic": "video-playback.XXXXXXXX",
"message": "{
\"type\": \"viewcount\",
\"server_time\": 1467437420.697452,
\"viewers\": 65
}"
}
}
```

At the time this document was written, the `message` you receive is a string containing a JSON message that must be further parsed.

## Event Types

The following sub-types are associated with video playback events and may be received:

### `stream-up`

This event is received when a channel goes online. The message will look like the following:

```json
{
"type": "MESSAGE",
"data": {
"topic": "video-playback.XXXXXXXX",
"message": "{
\"type\": \"stream-up\",
\"server_time\": 1467437420.697452,
\"play_delay\": 0
}"
}
}
```

##### Response Parameters

<table>
<thead>
<tr>
<th>Name</th>
<th width="50px">Type</th>
<th width="100%">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>type</code></td>
<td>string</td>
<td>The event sub-type</td>
</tr>
<tr>
<td><code>server_time</code></td>
<td>float</td>
<td>The current Unix time at the server, as seconds.</td>
</tr>
<tr>
<td><code>play_delay</code></td>
<td>int</td>
<td>The number of seconds of artificial playback delay set on a stream.</td>
</tr>
</tbody>
</table>

### `stream-down`

This event is received when a channel goes offline. The message will look like the following:

```json
{
"type": "MESSAGE",
"data": {
"topic": "video-playback.XXXXXXXX",
"message": "{
\"type\": \"stream-down\",
\"server_time\": 1467437420.697452
}"
}
}
```

##### Response Parameters

<table>
<thead>
<tr>
<th>Name</th>
<th width="50px">Type</th>
<th width="100%">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>type</code></td>
<td>string</td>
<td>The event sub-type</td>
</tr>
<tr>
<td><code>server_time</code></td>
<td>float</td>
<td>The current Unix time at the server, as seconds.</td>
</tr>
</tbody>
</table>

### `viewcount`

This event is received periodically as the number of users viewing a channel changes. The message will look like the following:

```json
{
"type": "MESSAGE",
"data": {
"topic": "video-playback.XXXXXXXX",
"message": "{
\"type\": \"viewcount\",
\"server_time\": 1467437420.697452,
\"viewers\": 65
}"
}
}
```

##### Response Parameters

<table>
<thead>
<tr>
<th>Name</th>
<th width="50px">Type</th>
<th width="100%">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>type</code></td>
<td>string</td>
<td>The event sub-type</td>
</tr>
<tr>
<td><code>server_time</code></td>
<td>float</td>
<td>The current Unix time at the server, as seconds.</td>
</tr>
<tr>
<td><code>viewers</code></td>
<td>int</td>
<td>The number of users viewing the stream.</td>
</tr>
</tbody>
</table>