reference.md

# Reference

## `/display`

> Updates and returns the new state of the display.

Optional Parameters:

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `large_channel` | string | Sets the channel name of the large screen.<br>This screen is the always visible main screen.<br>Set to *empty* to disable (see examples). |
| `small_channel` | string | Sets the channel name of the small screen.<br>This screen is a small Picture-in-Picture like screen in the top right corner.<br>Set to *empty* to disable (see examples). |
| `volume`        | float  | Sets the volume of the large screen.<br>Set to `#!java 0` or `#!java 0.0` to mute.<br>Values are in the range of `#!java 0.0 - 1.0`.<br> Note: The small screen is always muted.|
| `small_scale`   | float  | Sets the scale (size) of the small screen.<br>The value is relative to the width of the large screen.<br>Reasonable values are in the range of `#!java 0.2 - 0.5`.<br>It is best to just experiment with this setting. |
| `show_chat`     | bool   | Sets whether the chat should be shown or not.<br>Accepts `#!java true` and `#!java false`. |

!!! note
    All parameters are optional and can be combined. If none are supplied no updates are done and the current state gets returned.

Returns [`DisplayState`](#displaystate).

??? example "Examples"
    *   Only set the large_channel to riotgames
        <pre><code><http://localhost:8080/display?large_channel=riotgames></code></pre>
        ``` java
        /* JSONObject newState = */ client.display("riotgames", null, null, null, null);
        ```

    *   Set the large_channel to monstercat, disable the small_channel, set the volume to 0.8 and hide the chat.  
        Notice the small_scale is not changed (because of its absence)
        <pre><code><http://localhost:8080/display?large_channel=monstercat&small_channel=&volume=0.8&show_chat=false></code></pre>
        ``` java
        /* JSONObject newState = */ client.display("monstercat", "", 0.8f, null, false);
        ```

---

## `/twitch`

### `/twitch/getTopGames`

> Gets the most popular games on Twitch right now.

*No Parameters*

Returns [`Game`](#game) array.

??? example "Examples"
    *   Get top games
        <pre><code><http://localhost:8080/twitch/getTopGames></code></pre>
        ``` java
        List<JSONObject> topGames = client.twitchGetTopGames();
        ```

---

### `/twitch/searchGames`
> Searches games by query.

Parameters:

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| `query`   | string | What should be searched.<br>**Required** |

Returns [`Game`](#game) array.

??? example "Examples"
    *   Search for the "game" Talk Shows & Podcasts
        <pre><code><http://localhost:8080/twitch/searchGames?query=talk%20show></code></pre>
        ``` java
        List<JSONObject> foundGames = client.twitchSearchGames("talk show");
        ```

    *   Search for ove (will show games starting with "ove" like Overwatch)
        <pre><code><http://localhost:8080/twitch/searchGames?query=ove></code></pre>
        ``` java
        List<JSONObject> foundGames = client.twitchSearchGames("ove");
        ```

---

### `/twitch/getTopStreams`

> Gets the most popular streams on Twitch right now. Optionally filter by channels, game and language.

Optional Parameters:

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| `channels`    | string | Specify up to 100 channels separated by `,` that the search should be limited to.<br>See the examples why that would be useful. |
| `game`        | string | Specify a game that the search should be limited to. |
| `language`    | string | Specify a language that the search should be limited to. |

!!! note
    All parameters are optional and can be combined. If none are supplied the top streams for all channels, games and languages are returned.

Returns [`Stream`](#stream) array.

??? example "Examples"
    *   Get the unfiltered top streams
        <pre><code><http://localhost:8080/twitch/getTopStreams></code></pre>
        ``` java
        List<JSONObject> topStreams = client.twitchGetTopStreams(null, null, null);
        ```

    *   German top streams
        <pre><code><http://localhost:8080/twitch/getTopStreams?language=de></code></pre>
        ``` java
        List<JSONObject> topStreams = client.twitchGetTopStreams(null, null, "de");
        ```

    *   English top streams in Talk Shows and Podcasts
        <pre><code><http://localhost:8080/twitch/getTopStreams?language=en&game=Talk%20Shows%20%26%20Podcasts></code></pre>
        ``` java
        List<JSONObject> topStreams = client.twitchGetTopStreams(null, "Talk Shows and Podcasts", "en");
        ```

    *   Tip: If your app implements a favorite list you can very easily query these channels and see who is streaming and other information
        <pre><code><http://localhost:8080/twitch/getTopStreams?channels=xqcow,dafran,kitboga></code></pre>
        ``` java
        String[] favoriteChannels = {"xqcow", "dafran", "kitboga"};

        List<JSONObject> topStreams = client.twitchGetTopStreams(favoriteChannels, null, null);
        ```

---

### `/twitch/getFeaturedStreams`

> Gets the featured streams on Twitch's homepage.

*No Parameters*

Returns [`Stream`](#stream) array.

??? example "Examples"
    *   Get featured streams
        <pre><code><http://localhost:8080/twitch/getFeaturedStreams></code></pre>
        ``` java
        List<JSONObject> featuredStreams = client.twitchGetFeaturedStreams();
        ```

---

## JSON Structures <small>(by Example)</small>

### DisplayState
``` json
{
	"large_channel": "xqcow",
	"small_channel": "",
	"volume": 0.75,
	"small_scale": 0.25,
	"show_chat": true
}
```

### Game
``` json
{
    "name": "Grand Theft Auto V",
    "viewers": 118716,
    "box_img_url": "https://static-cdn.jtvnw.net/ttv-boxart/Grand%20Theft%20Auto%20V-272x380.jpg",
    "logo_img_url": "https://static-cdn.jtvnw.net/ttv-logoart/Grand%20Theft%20Auto%20V-240x144.jpg"
}
```

### Stream
``` json
{
    "average_fps": 60,
    "started_at": "2019-08-20T19:54:47Z",
    "game": "Fortnite",
    "preview_img_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_tfue-640x360.jpg",
    "video_height": 1080,
    "viewers": 42870,
    "status": "High Kill Solos",
    "language": "en",
    "mature": false,
    "channel_name": "tfue",
    "channel_display_name": "Tfue",
    "channel_logo_img_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/2470b5c6-a737-4ba6-8987-c28e0ca839e1-profile_image-300x300.jpg"
}
```

!!! note
    * The image at the `preview_img_url` url updates itself every couple of seconds. If the app uses preview images it could also.
    * `started_at` is an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
    * `video_height`: `#!json 1080` = `HD`, `#!json < 1080` = `SD`, `#!json > 1080` = `UHD`.
    * `mature`: If the stream is meant for mature audiences (set by the streamer themselves as a guideline).