Stream APIs Documentation

The StreamController manages web socket functionalities, which are used to send realtime updates to clients from the server. This could be queue changes or request for play/pause/skip, primarily when a client wants to control another client, for example adding songs to the current play queue on a TV client from the user's phone client. For more information about how WebSockets are used, see the WebSocket Architecture.

Controller Route: /api/stream

All routes within the StreamController are prefixed by /api/stream.

---

Summary of Endpoints

Endpoint	Method	Description	Authorization
/api/stream/connect	GET	Connects to a WebSocket for streaming.	Admin, User, Pass
/api/stream/get-external	GET	Retrieves available external devices for streaming.	Admin, User
/api/stream/play-external	GET	Sends a play request to an external device.	Admin, User
/api/stream/pause-external	GET	Sends a pause request to an external device.	Admin, User
/api/stream/skip-external	GET	Sends a skip request to an external device.	Admin, User
/api/stream/rewind-external	GET	Sends a rewind request to an external device.	Admin, User
/api/stream/volume-external	GET	Adjusts the volume on an external device.	Admin, User

---

Connect to WebSocket Stream

Connects the client to a WebSocket for streaming.

Details:

• Endpoint: /api/stream/connect
• Method: GET
• Authorization: JWT (Roles: Admin, User, Pass)

Responses:

• 200 OK: Successfully connected to the WebSocket.
• 400 Bad Request: If the request is not a WebSocket request.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/connect" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Get External Devices

Fetches a list of available external devices that the user can stream to.

Details:

• Endpoint: /api/stream/get-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Responses:

• 200 OK: Returns a list of external devices.
• 404 Not Found: If no devices are available.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/get-external" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Play on External Device

Sends a play request to a specified external device to start playing from a queue.

Details:

• Endpoint: /api/stream/play-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Parameters:

• deviceName (string, required): The name of the external device.
• queueId (string, required): The ID of the queue to play.

Responses:

• 200 OK: Play request sent successfully.
• 404 Not Found: If the device is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/play-external?deviceName=Speaker&queueId=queue123" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Pause on External Device

Sends a pause request to a specified external device.

Details:

• Endpoint: /api/stream/pause-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Parameters:

• deviceName (string, required): The name of the external device.

Responses:

• 200 OK: Pause request sent successfully.
• 404 Not Found: If the device is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/pause-external?deviceName=Speaker" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Skip on External Device

Sends a skip request to a specified external device.

Details:

• Endpoint: /api/stream/skip-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Parameters:

• deviceName (string, required): The name of the external device.

Responses:

• 200 OK: Skip request sent successfully.
• 404 Not Found: If the device is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/skip-external?deviceName=Speaker" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Rewind on External Device

Sends a rewind request to a specified external device.

Details:

• Endpoint: /api/stream/rewind-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Parameters:

• deviceName (string, required): The name of the external device.

Responses:

• 200 OK: Rewind request sent successfully.
• 404 Not Found: If the device is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/rewind-external?deviceName=Speaker" \
             -H "Authorization: Bearer <JWT-token>"
        

---

Set Volume on External Device

Sends a volume adjustment request to a specified external device.

Details:

• Endpoint: /api/stream/volume-external
• Method: GET
• Authorization: JWT (Roles: Admin, User)

Parameters:

• deviceName (string, required): The name of the external device.
• volume (int, optional): The volume level to set (default is 50).

Responses:

• 200 OK: Volume adjustment request sent successfully.
• 404 Not Found: If the device is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stream/volume-external?deviceName=Speaker&volume=75" \
             -H "Authorization: Bearer <JWT-token>"