Commit 07e1b848 authored by Simon Kirsten's avatar Simon Kirsten
Browse files

Server docs are now mostly complete with only small snippets missing

parent 618415c0
......@@ -50,17 +50,15 @@ Darwin (macOS) | x86 (64-bit) | [stream-tv-server](../binaries/darwin-x86_64/s
## Common Errors
<small>TODO</small>
```
listen tcp :80: bind: permission denied
```
: The port range below 1024 is restricted on \*nix systems to superusers ([more info](https://unix.stackexchange.com/a/16568)).
Either run as superuser `sudo ./stream-tv-server` or change the port via the [command-line options](options.md).
```
listen tcp :80: bind: address already in use
listen tcp 0.0.0.0:8080: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
```
: Something is already using the port. This could be another Stream TV Server instance or some other application (like a webserver).
Close / disable the other service or change the port via the [command-line options](options.md).
- <small>`listen tcp 0.0.0.0:80: bind: permission denied`</small>
The port range below 1024 is restricted on \*nix systems to superusers ([more info](https://unix.stackexchange.com/a/16568)).
Either run as superuser `sudo ./stream-tv-server -p 80` or change the port.
- <small>`listen tcp 0.0.0.0:8080: bind: address already in use`</small>
<small>`listen tcp 0.0.0.0:8080: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.`</small>
Something is already using the port. This could be another Stream TV Server instance or some other application (like a webserver).
Close / disable the other service or change the port via the [command-line options](options.md).
# Command Line Options
!!! info
The default options are totally fine for most users. You can skip this one.
By default the server listens on all IPs on port 8080.
This is totally fine for most users. You can skip this one.
```bash
$ ./stream-tv-server --help
......@@ -13,14 +14,18 @@ NAME:
USAGE:
stream-tv-server.exe [global options] [arguments...]
VERSION:
v0.9.1-1daaad39
GLOBAL OPTIONS:
--port value, -p value http port to listen on (default: 8080)
--browser, -b automatically open the default browser
--local, -l only listen on 127.0.0.1 (see doc)
--help, -h show help
--version, -v print the version
```
By default stream-tv-server listens on all local ip addresses on port 8080. This means that it is exposed to the local network (LAN / WLAN) which is needed if the app is on a phone. Note that the phone must be in the same network as the computer / laptop.
By default stream-tv-server listens on all ip addresses on port 8080. This means that it is exposed to the local network (LAN / WLAN) which is needed if the app is on a phone. Note that the phone must be in the same network as the computer / laptop.
When using the Android Emulator on the same device as the server this exposure is not necessary. Use the `--local` flag to only listen on `127.0.0.1` aka `localhost`. The emulator must then connect to `10.0.2.2` as described here:
......
......@@ -15,18 +15,14 @@ Stop with Ctrl-C or close this terminal.
In the examples of this documentation only the local address is used. If you want to connect from your phone or the emulator you need to use the network address (`192.168.0.136` in this case). Also we assume you use the default port `8080`.
1. Open http://127.0.0.1:8080 in a browser.
1. Open <http://127.0.0.1:8080> in a browser. Leave this tab / window open while you do the other steps.
2. Get the current state of the tv:
``` tab="Browser"
http://127.0.0.1:8080/tv/state
```
``` bash tab="Bash"
curl "http://127.0.0.1:8080/tv/state"
```
``` java tab="Java"
``` java tab="Remote (Android)"
TODO
```
......@@ -36,7 +32,7 @@ Stop with Ctrl-C or close this terminal.
"large_channel": null,
"small_channel": null,
"volume": 0.5,
"small_scale": 0.5,
"small_scale": 0.3,
"show_chat": false
}
```
......@@ -47,11 +43,7 @@ Stop with Ctrl-C or close this terminal.
http://127.0.0.1:8080/twitch/streams/top
```
``` bash tab="Bash"
curl "http://127.0.0.1:8080/twitch/streams/top"
```
``` java tab="Java"
``` java tab="Remote (Android)"
TODO
```
......@@ -82,11 +74,7 @@ Stop with Ctrl-C or close this terminal.
http://127.0.0.1:8080/tv/state?large_channel={channel here}&volume=0&show_chat=true
```
``` bash tab="Bash"
curl "http://127.0.0.1:8080/tv/state?large_channel={channel here}&volume=0&show_chat=true"
```
``` java tab="Java"
``` java tab="Remote (Android)"
TODO
```
......@@ -95,10 +83,12 @@ Stop with Ctrl-C or close this terminal.
{
"large_channel": "riotgames",
"small_channel": null,
"volume": 0.5,
"small_scale": 0.5,
"show_chat": false
"volume": 0,
"small_scale": 0.3,
"show_chat": true
}
```
The tab / window from step 1 should now start playing that stream with the provided settings.
5. Read the [Reference](reference.md).
\ No newline at end of file
......@@ -6,25 +6,30 @@
> Updates and returns the new state of the TV.
Optional Query String Parameter:
Optional Query String Parameters:
| Name | Type | Description |
| --------------- | ------ | --- |
| `large_channel` | string | Sets the channel name of the large screen.<br>This screen is always visible. Set to `#!java null` to disable.<br>Example: `large_channel=monstercat` |
| `small_channel` | string | Sets the channel name of the small screen.<br>This screen is only visible if it is not `#!java null`. Set to `#!java null` to disable.<br>Example: `small_channel=null` |
| `volume` | float | Sets the volume of the large screen.<br>The small screen is always muted. Set to `#!java 0` or `#!java 0.0` to mute.<br>Values are in the range of `#!java 0.0 - 1.0`.<br>Example: `volume=0.75` |
| `small_scale` | float | Sets the scale (size) of the small screen.<br>Reasonable values are in the range of `#!java 0.2 - 0.8`.<br>It is best to just experiment with this setting.<br>Example: `small_scale=0.4` |
| `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.<br>Example: `small_scale=0.4` |
| `show_chat` | bool | Sets whether the chat should be shown or not.<br>Example: `show_chat=true` |
!!! note
All parameters are optional. If none are supplied no updates are done and the current state gets returned. Also empty parameters like `?large_channel=&volume=` are simply ignored. This makes the Java integration a lot simpler.
All parameters are optional and can be combined. If none are supplied no updates are done and the current state gets returned. Also empty parameters like `?large_channel=&volume=` are simply ignored. This makes the Android integration a lot simpler.
Returns: [`TVState`](#tvstate_1).
Examples:
* `http://127.0.0.1:8080/tv/state?large_channel=riotgames&small_channel=&volume=0.75&show_chat=true`
* <small>TODO</small>
``` tab="Browser"
http://127.0.0.1:8080/tv/state?large_channel=riotgames&small_channel=&volume=0.75&show_chat=true
```
``` java tab="Remote (Android)"
TODO
```
---
......@@ -32,58 +37,96 @@ Examples:
### `/twitch/games/top`
> Gets the most popular games on twitch right now.
> Gets the most popular games on Twitch right now.
*No Parameters*
Returns: [`Game`](#game) array.
Examples:
``` tab="Browser"
http://127.0.0.1:8080/twitch/games/top
```
``` java tab="Remote (Android)"
TODO
```
---
### `/twitch/games/search`
> Searches games by query.
Query String Parameter:
Query String Parameters:
| Name | Type | Description |
| --------------- | ------ | --- |
| `query` | string | What should be searched e.g. `query=Talk%20Shows` |
| `query` | string | What should be searched e.g. `query=Talk%20Shows`<br>**Required** |
Returns: [`Game`](#game) array.
Examples:
``` tab="Browser"
http://127.0.0.1:8080/twitch/games/search?query=Talk%20Shows
```
``` java tab="Remote (Android)"
TODO
```
---
### `/twitch/streams/top`
> Gets the most popular streams on twitch right now. Optionally filter by channels, game and language.
> Gets the most popular streams on Twitch right now. Optionally filter by channels, game and language.
Optional Query String Parameter:
Optional Query String Parameters:
| Name | Type | Description |
| --------------- | ------ | --- |
| `channels` | string | Specify up to 100 channels seperated by `,` that the search should be limited to. See the Note why that would be useful.<br>Example: `channels=xqcow,dafran,kitboga` |
| `channels` | string | Specify up to 100 channels seperated by `,` that the search should be limited to. See the note why that would be useful.<br>Example: `channels=xqcow,dafran,kitboga` |
| `game` | string | Specify a game that the search should be limited to.<br>Example: `game=overwatch` |
| `language` | string | Specify a language that the search should be limited to.<br>Example: `language=de` |
!!! note
All parameters are optional. Empty parameters like `?channels=&language=` are simply ignored. This makes the Java integration a lot simpler.
All parameters are optional and can be combined. Empty parameters like `?channels=&language=` are simply ignored. This makes the Android integration a lot simpler.
The `channels` option can be very usefull: If for example your app implements a favorite list you can very easily query these channels `http://127.0.0.1:8080/twitch/streams/top?channels={comma seperated list of favorite channels here}` and see who is streaming and other metadata.
Returns: [`Stream`](#stream) array.
Examples:
* `http://127.0.0.1:8080/twitch/streams/top?game=Talk%20Shows%20%26%20Podcasts&language=en`
* <small>TODO</small>
``` tab="Browser"
http://127.0.0.1:8080/twitch/streams/top?game=Talk%20Shows%20%26%20Podcasts&language=en
```
``` java tab="Remote (Android)"
TODO
```
---
### `/twitch/streams/featured`
> Gets the featured games on twitch's homepage.
> Gets the featured games on Twitch's homepage.
*No Parameters*
Returns: [`Stream`](#stream) array.
Examples:
``` tab="Browser"
http://127.0.0.1:8080/twitch/streams/featured
```
``` java tab="Remote (Android)"
TODO
```
---
## JSON Structures <small>(by Example)</small>
......@@ -125,4 +168,8 @@ Returns: [`Stream`](#stream) array.
"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"
}
```
\ No newline at end of file
```
Note that the image at the `preview_img_url` url updates itself every couple of seconds <small>TODO research how many seconds</small>. This could be used to display a *"live"* preview in the app.
Also note that `started_at` is an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment