client-api-spec.json

{
	"openapi": "3.1.0",
	"info": {
		"title": "Uniview Client",
		"version": "1.0",
		"summary": "Interact with your local Uniview client",
		"description": "This API is intended to allow controlling the uniview client from other programs to make UI development easier.",
		"contact": {
			"name": "Mailinglist",
			"url": "https://lists.sr.ht/~mpldr/uniview",
			"email": "~mpldr/uniview@lists.sr.ht"
		},
		"x-logo": {
			"href": "https://sr.ht/~mpldr/uniview",
			"url": "https://raw.githubusercontent.com/mpldr/cdn/main/icon.webp",
			"altText": "Uniview Logo"
		},
		"license": {
			"name": "GNU AGPLv3",
			"url": "https://www.gnu.org/licenses/agpl.txt"
		}
	},
	"servers": [
		{
			"url": "http://[::1]:21558",
			"description": "Localhost"
		}
	],
	"paths": {
		"/status": {
			"parameters": [],
			"get": {
				"summary": "Query system status",
				"operationId": "get-status",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Status"
								},
								"examples": {
									"example": {
										"value": {
											"connection": "ok",
											"player": "mpv",
											"version": {
												"major": 0,
												"minor": 2,
												"patch": 1
											}
										}
									}
								}
							}
						}
					},
					"503": {
						"description": "Service Unavailable",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Status"
								},
								"examples": {
									"example": {
										"value": {
											"connection": "connecting",
											"player": "mpv",
											"version": {
												"major": 0,
												"minor": 2,
												"patch": 1
											}
										}
									}
								}
							}
						}
					}
				},
				"description": "Returns information on the client currently used.",
				"tags": [
					"system"
				]
			}
		},
		"/player/pause": {
			"get": {
				"summary": "retrieve pause state",
				"tags": [
					"player"
				],
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Pause",
									"description": "the pause state"
								}
							}
						}
					}
				},
				"operationId": "get-player-pause",
				"description": "Query the player state on whether it is currently paused and provides the playback position if it is."
			},
			"put": {
				"summary": "set player pause state",
				"operationId": "put-player-pause",
				"responses": {
					"202": {
						"description": "Accepted"
					}
				},
				"description": "Set the player into the given pause state.",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"type": "boolean",
								"description": "set pause state to this value"
							}
						}
					},
					"required": true
				},
				"tags": [
					"player"
				]
			}
		},
		"/player/position": {
			"get": {
				"summary": "retrieve current position",
				"tags": [
					"player"
				],
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PlaybackPosition"
								}
							}
						}
					}
				},
				"operationId": "get-player-position",
				"description": "Query the player for its current playback position"
			},
			"put": {
				"summary": "seek to position",
				"operationId": "put-player-position",
				"responses": {
					"202": {
						"description": "Accepted",
						"content": {}
					}
				},
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/PlaybackPosition"
							}
						}
					},
					"required": true
				},
				"tags": [
					"player"
				],
				"description": "Seek to the specified position."
			}
		},
		"/files": {
			"get": {
				"summary": "list file roots",
				"description": "",
				"operationId": "",
				"tags": [
					"filesysten"
				],
				"parameters": [],
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"type": "string",
										"description": "the root path"
									},
									"description": "a list of available roots"
								},
								"examples": {
									"example": {
										"value": [
											"/home/user/Videos",
											"/mnt/media/Anime"
										]
									}
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/files/{root}": {
			"get": {
				"summary": "list files under the given root",
				"description": "",
				"operationId": "get-files-root-relpath",
				"tags": [
					"filesysten"
				],
				"parameters": [
					{
						"in": "query",
						"name": "relpath",
						"description": "relative path to search",
						"schema": {
							"type": "string"
						}
					}
				],
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Directory"
								}
							}
						},
						"description": "OK"
					},
					"404": {
						"description": "Not Found"
					}
				}
			},
			"parameters": [
				{
					"in": "path",
					"name": "root",
					"description": "id of the file root to check",
					"schema": {
						"type": "integer",
						"minimum": 0
					},
					"required": true
				}
			]
		},
		"/player/start": {
			"post": {
				"summary": "start playback of a video",
				"description": "",
				"operationId": "",
				"tags": [
					"player"
				],
				"parameters": [],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"oneOf": [
									{
										"$ref": "#/components/schemas/VideoFile"
									},
									{
										"$ref": "#/components/schemas/VideoStream"
									}
								]
							}
						}
					},
					"description": "start playback of a file"
				},
				"responses": {
					"202": {
						"description": "Accepted"
					},
					"400": {
						"description": "Bad Request"
					},
					"404": {
						"description": "Not Found"
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"Status": {
				"title": "Status",
				"type": "object",
				"properties": {
					"connection": {
						"type": "string",
						"enum": [
							"ok",
							"connecting",
							"disconnected"
						],
						"description": "the currect connection status"
					},
					"player": {
						"type": "string",
						"example": "mpv",
						"description": "the used player interface"
					},
					"version": {
						"$ref": "#/components/schemas/Version",
						"description": "the program version"
					}
				},
				"description": "Holds information on the currently running client",
				"required": [
					"version",
					"connection",
					"player"
				]
			},
			"Version": {
				"title": "Version",
				"type": "object",
				"properties": {
					"major": {
						"type": "integer",
						"minimum": 0,
						"description": "the major version number"
					},
					"minor": {
						"type": "integer",
						"minimum": 0,
						"description": "the minor version number"
					},
					"patch": {
						"type": "integer",
						"minimum": 0,
						"description": "the patchlevel"
					},
					"suffix": {
						"type": "string",
						"description": "a potential suffix, if provided"
					}
				},
				"required": [
					"major",
					"minor",
					"patch"
				],
				"description": "A semver compatible version"
			},
			"Pause": {
				"title": "Pause Information",
				"type": "object",
				"description": "Holds information on the players pause state.",
				"properties": {
					"paused": {
						"type": "boolean",
						"description": "the paused state"
					},
					"paused-at": {
						"$ref": "#/components/schemas/PlaybackPosition",
						"description": "the timestamp the video was paused at"
					}
				},
				"required": [
					"paused"
				]
			},
			"PlaybackPosition": {
				"title": "PlaybackPosition",
				"type": "number",
				"minimum": 0,
				"format": "float",
				"example": 184.32,
				"description": "the current playback position"
			},
			"File": {
				"type": "object",
				"properties": {
					"name": {
						"type": "string",
						"description": "the filename"
					},
					"directory": {
						"type": "boolean",
						"description": "true if the file is a directory"
					}
				},
				"required": [
					"name",
					"directory"
				]
			},
			"Directory": {
				"type": "object",
				"properties": {
					"root": {
						"type": "integer",
						"description": "the id of the root"
					},
					"relative_path": {
						"type": "string",
						"description": "the path relative to the root to reach this directory"
					},
					"content": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/File"
						},
						"description": "the files contained in this directory"
					}
				},
				"required": [
					"root",
					"relative_path",
					"content"
				]
			},
			"VideoFile": {
				"type": "object",
				"properties": {
					"root": {
						"type": "integer",
						"minimum": 0,
						"description": "the root the file is under"
					},
					"relativePath": {
						"type": "string",
						"description": "the relative path to the file"
					}
				},
				"required": [
					"root",
					"relativePath"
				]
			},
			"VideoStream": {
				"type": "string",
				"description": "the URL to play"
			}
		},
		"responses": {},
		"examples": {},
		"parameters": {}
	},
	"externalDocs": {
		"description": "Wiki",
		"url": "https://man.sr.ht/~mpldr/uniview"
	}
}