Commit b354df9c authored by Simon Kirsten's avatar Simon Kirsten
Browse files

Updated server documentation

parent ea77c794
Pipeline #22236 passed with stages
in 1 minute and 15 seconds
# Author's notes
!!! example "*TODO*"
* This could be moved to about
\ No newline at end of file
# Stream TV Server
!!! example "*TODO*"
* this is a lot of content making it feel convoluted
## Download
OS | CPU Platform | Download
......@@ -18,30 +14,30 @@ Darwin (macOS) | x86 (64-bit) | [stream-tv-server-darwin-x86_64](https://code.f
 | x86 (32-bit) | [stream-tv-server-linux-x86](https://code.fbi.h-da.de/simons-nzse-2/stream-tv/-/jobs/artifacts/master/raw/stream-tv-server-darwin-x86?job=server)
!!! tip
In the following documentation the specific executable e.g. `stream-tv-server-windows-x86_64.exe` is always referenced as `stream-tv-server`.
For simplicity sake you should also rename your executable to `stream-tv-server` or `stream-tv-server.exe` (on Windows).
In the following documentation the specific executable e.g. `stream-tv-server-windows-x86_64.exe` is always refered to as `stream-tv-server`.
For simplicity's sake you should also rename your executable to `stream-tv-server` or `stream-tv-server.exe` (on Windows).
??? expert info
If you do not wish to use a precompiled executable you can [compile and / or develop on your machine.](contributing.md).
If you do not wish to use a precompiled executable you can [compile it yourself](contributing.md).
## Run
### Windows
1. Just double-click the exe or run it in a cmd or PowerShell `.\stream-tv-server`.
2. *Optional:* provide [command-line options](options.md) e.g. `.\stream-tv-server --open-browser :9090`
1. Just double-click the exe or run it in a cmd or PowerShell `.\stream-tv-server.exe`.
2. *Optional:* Provide [command-line options](options.md).
!!! warning
If you get [this](/assets/windows-protected-your-pc.png) *"Windows proteced your PC"* warning press <kbd>More info</kbd> and <kbd>Run anyway</kbd>.
### Linux
1. Assign the file execute permission in a terminal: `chmod +x stream-tv-server`.
2. Run it in a terminal `./stream-tv-server`.
3. *Optional:* provide [command-line options](options.md) e.g. `./stream-tv-server --open-browser :9090`
2. Run it from the terminal `./stream-tv-server`.
3. *Optional:* Provide [command-line options](options.md).
### Darwin (macOS) <small>in the Terminal</small>
1. Assign the file execute permission in a terminal: `chmod +x stream-tv-server`.
2. Run it from the terminal `./stream-tv-server`.
3. *Optional:* Provide [command-line options](options.md) e.g. `./stream-tv-server --open-browser :9090`
3. *Optional:* Provide [command-line options](options.md).
### Darwin (macOS) <small>from the GUI</small>
1. Assign the file execute permission in a terminal: `chmod +x stream-tv-server`.
......@@ -67,10 +63,6 @@ listen tcp :80: bind: permission denied
```
listen tcp :80: bind: address already in use
```
: Something is already using the port 80. This could be another Stream TV Server instance or some other application (like a webserver).
Close / disable the other application or change the port via the [command-line options](options.md).
## Testing
: 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).
The quickest way to get familiar with the functionality is to check out the [Remote Test Page](../remote/testpage.md).
\ No newline at end of file
# License
!!! example "*TODO*"
We should really have a license but idk if MIT is the right one and who actually has copyright here (and who should)
We should really have a license but idk if MIT is the right one and who actually has copyright here...
**MIT License**
......
# Command Line Options
!!! info
The default options are totally fine for most use cases. You can skip this one.
The default options are totally fine for most users. You can skip this one.
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).
```bash
$ ./stream-tv-server --help
```
```
NAME:
stream-tv-server.exe - Stream TV Server https://simons-nzse-2.h-da.io/stream-tv/server/
!!! example "*TODO: talk about*"
* praktikum
* emulator
* implement auto close
USAGE:
stream-tv-server.exe [global options] [arguments...]
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
```
Usage of stream-tv-server:
-b Automatically open the default browser (shorthand)
-browser
Automatically open the default browser
-l string
Address to listen on (shorthand) (default ":8080")
-listen string
Address to listen on (default ":8080")
```
The `-l` / `-listen` option supports the same options as [`net.Dial`](https://golang.org/pkg/net/#Dial).
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.
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:
* `:80`, `:http`, `0.0.0.0:80`, etc. listens on all addresses port 80
* `localhost:8080`
\ No newline at end of file
> Also note that the address 127.0.0.1 on your development machine corresponds to the emulator's own loopback interface. If you want to access services running on your development machine loopback interface (a.k.a. 127.0.0.1 on your machine), you should use the special address 10.0.2.2 instead.
>
> [Android Studio - User guide](https://developer.android.com/studio/run/emulator-networking#networkaddresses)
# Usage
```bash
$ ./stream-tv-server
```
```
Serving on
http://127.0.0.1:8080
http://192.168.0.136:8080
Read the documentation at https://simons-nzse-2.h-da.io/stream-tv/server/usage/ on how to use this server.
Stop with Ctrl-C or close this terminal.
```
## Quickstart
!!! note
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.
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"
TODO
```
``` json
{
"large_channel": null,
"small_channel": null,
"volume": 0.5,
"small_scale": 0.5,
"show_chat": false
}
```
3. Find some stream on twitch:
``` tab="Browser"
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"
TODO
```
``` json
[
{
"average_fps": 60,
"started_at": "2019-08-18T17:29:55Z",
"game": "League of Legends",
"preview_img_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_riotgames-640x360.jpg",
"video_height": 1080,
"viewers": 226699,
"status": "TL vs. CG | Semifinals Day 2 | LCS Summer Split | Team Liquid vs. Clutch Gaming (2019)",
"language": "en",
"mature": false,
"channel_name": "riotgames",
"channel_display_name": "Riot Games",
"channel_logo_img_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/889e7697-b636-48d9-be15-a9a39e286a64-profile_image-300x300.png"
},
...
]
```
4. Start playback of that stream:
``` tab="Browser"
http://127.0.0.1:8080/tv/state?large_channel=riotgames
```
``` bash tab="Bash"
curl "http://127.0.0.1:8080/tv/state?large_channel=riotgames"
```
``` java tab="Java"
TODO
```
``` json
{
"large_channel": "riotgames",
"small_channel": null,
"volume": 0.5,
"small_scale": 0.5,
"show_chat": false
}
```
## `/tv`
### `/tv/state`
> Updates and returns the new state of the TV.
Optional Query String Parameter:
| 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` |
| `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.
Returns: [`TVState`](#TVState).
Examples:
* `http://127.0.0.1:8080/tv/state?large_channel=riotgames&small_channel=&volume=0.75&show_chat=true`
* <small>TODO</small>
## `/twitch`
### `/twitch/games/top`
> Gets the most popular games on twitch right now.
*No Parameters*
Returns: [`Game`](#Game) array.
### `/twitch/streams/top`
> Gets the most popular streams on twitch right now. Optionally filter by channels, game and language.
Optional Query String Parameter:
| 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` |
| `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.
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=Overwatch&language=en`
* <small>TODO</small>
### `/twitch/streams/featured`
> Gets the featured games on twitch's homepage.
*No Parameters*
Returns: [`Stream`](#Stream) array.
\ No newline at end of file
site_name: Stream TV Project Documentation
site_description: TODO
site_author: Simon Kirsten
site_url: https://simons-nzse-2.h-da.io/stream-tv
site_url: https://simons-nzse-2.h-da.io/stream-tv/
# Repository
repo_name: simons-nzse-2/stream-tv
......@@ -87,8 +87,8 @@ nav:
- Server:
- Stream TV Server: server/index.md
- Options: server/options.md
- Usage: server/usage.md
- Release notes: server/release-notes.md
- Author's notes: server/authors-notes.md
- Contributing: server/contributing.md
- License: server/license.md
......
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