feat: Usage document (#212)

README.md

@@ -9,45 +9,44 @@
   <b text-align="center"> Bluecherry DVR client to run across range of devices.</b>
   <br/>
 
-  <a href="https://www.bluecherrydvr.com/">Website</a> •
-  <a href="https://www.bluecherrydvr.com/product/v3license/">Purchase</a> •
-  <a href="https://www.bluecherrydvr.com/chat/">Chat</a>
-</div>
+<a href="https://www.bluecherrydvr.com/">Website</a> •
+<a href="https://www.bluecherrydvr.com/product/v3license/">Purchase</a> •
+<a href="https://www.bluecherrydvr.com/chat/">Chat</a>
 
+</div>
 
 ## Features
 
-* 🖲️ Ability to add multiple [Bluecherry DVR servers](https://www.bluecherrydvr.com/downloads/).
-* 📺 Play any stream or recording from the web.
-* 🎛️ Interactive camera grid viewer, with support for multiple layouts:
+- 🖲️ Ability to add multiple [Bluecherry DVR servers](https://www.bluecherrydvr.com/downloads/).
+- 📺 Play any stream or recording from the web.
+- 🎛️ Interactive camera grid viewer, with support for multiple layouts:
   <br /> $~~~~$
-💻 For larger screens, compact and multiple layout views are available.
+  💻 For larger screens, compact and multiple layout views are available.
   <br /> $~~~~~$📱 For smaller screens, see multiple cameras in 2x3, 2x2, 2x1 or 1x1 view
   <br /> $~~~~~$👆 Re-orgderable drag-and-drop camera viewer
   <br /> $~~~~~$🛞 Cycle through different layout views automatically
-* 🔎 Pinch-to-zoom fullscreen camera viewer.
-* 📹 Multicast streams support
-* 🏃 Events List Viewer
-* 🚡 Events Timeline Viewer
-* 📸 Direct camera viewer.
-* 🎮 **P**an-**T**ilt-**Z**oom controls for supported cameras.
-* 🌓 Light & dark app theme.
-* 📰 System camera event notifications.
-* 📺 Adaptive and responsive design for larger screens
-* 📱 Cross-platform
+- 🔎 Pinch-to-zoom fullscreen camera viewer.
+- 📹 Multicast streams support
+- 🏃 Events List Viewer
+- 🚡 Events Timeline Viewer
+- 📸 Direct camera viewer.
+- 🎮 **P**an-**T**ilt-**Z**oom controls for supported cameras.
+- 🌓 Light & dark app theme.
+- 📰 System camera event notifications.
+- 📺 Adaptive and responsive design for larger screens
+- 📱 Cross-platform
   <br /> $~~~~$📱 Mobile: Android & iOS
   <br /> $~~~~$🖥️ Desktop: Windows, Linux & MacOS
-* 📦 Automatic updates
-
+- 📦 Automatic updates
 
 ## Download
 
-| Android | iOS | Windows | GNU/Linux | MacOS |
-| ------- | --- | ------- | ----- | ----- |
-| [arm64 `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-arm64-v8a-release.apk) | [App Store](https://apps.apple.com/us/app/bluecherry-mobile/id1555805139) | [Windows Setup](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-windows-setup.exe) | [AppImage](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.AppImage) | [Executable `.app`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-macos.7z)  |
-| [armabi `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-armeabi-v7a-release.apk) |  | 🚧 **SOON** ~~`winget install bluecherry`~~ | [Ubuntu/Debian `.deb`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.deb) | 🚧 **SOON** ~~[App Store](https://github.com/bluecherrydvr/unity/issues/112)~~ |
-| [x86_64 `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-x86_64-release.apk) |  | 🚧 **SOON** ~~Microsoft Store~~ | [Raw Executable `.tar.gz`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.tar.gz) |  |
-| 🚧 **SOON** ~~Play Store~~ |  |  | [Fedora/Red Hat Linux `.rpm`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.rpm) |  |
+| Android                                                                                                                            | iOS                                                                       | Windows                                                                                                              | GNU/Linux                                                                                                                         | MacOS                                                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| [arm64 `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-arm64-v8a-release.apk)    | [App Store](https://apps.apple.com/us/app/bluecherry-mobile/id1555805139) | [Windows Setup](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-windows-setup.exe) | [AppImage](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.AppImage)               | [Executable `.app`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-macos.7z) |
+| [armabi `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-armeabi-v7a-release.apk) |                                                                           | 🚧 **SOON** ~~`winget install bluecherry`~~                                                                          | [Ubuntu/Debian `.deb`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.deb)        | 🚧 **SOON** ~~[App Store](https://github.com/bluecherrydvr/unity/issues/112)~~                                  |
+| [x86_64 `.apk`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-android-x86_64-release.apk)      |                                                                           | 🚧 **SOON** ~~Microsoft Store~~                                                                                      | [Raw Executable `.tar.gz`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.tar.gz) |                                                                                                                 |
+| 🚧 **SOON** ~~Play Store~~                                                                                                         |                                                                           |                                                                                                                      | [Fedora/Red Hat Linux `.rpm`](https://github.com/bluecherrydvr/unity/releases/download/bleeding_edge/bluecherry-linux-x86_64.rpm) |                                                                                                                 |
 
 Or download the latest release [here](https://github.com/bluecherrydvr/unity/releases).
 
@@ -58,15 +57,20 @@ Most platforms will not require any extra steps to install the app.
 #### Linux
 
 You need mpv & libmpv-dev installed:
+
 ```bash
 sudo apt install mpv libmpv-dev
 ```
 
 To install the `.deb` file, run:
+
 ```bash
 sudo dpkg -i bluecherry-linux-x86_64.deb
 ```
 
+## Usage
+
+Refer to [USAGE.md](./USAGE.md) for detailed usage instructions.
 
 ## License
 
@@ -160,7 +164,7 @@ flutter pub get
 flutter build [linux|windows|macos|android|ios]
 ```
 
-The automated build process is done using GitHub Actions. You may find the workflow [here](.github/workflows/main.yml). The workflow builds the app for all supported platforms & uploads the artifacts to the release page. 
+The automated build process is done using GitHub Actions. You may find the workflow [here](.github/workflows/main.yml). The workflow builds the app for all supported platforms & uploads the artifacts to the release page.
 
 On Linux, a Flutter executable with different environment variables is used to build the app for different distributions. This tells the app how the system is configured and how it should install updates. To run for Linux, you need to provide the following environment variables based on your system, where `[DISTRO_ENV]` can be `appimage` (AppImage), `deb` (Debian), `rpm` (RedHat), `tar.gz` (Tarball) or `pi` (Raspberry Pi).
 

USAGE.md

@@ -0,0 +1,208 @@
+# Usage
+
+This document explains how to use the Bluecherry Client and list all its features.
+
+## Table of contents
+
+- [Overview](#overview)
+- [Download, Installation](#download-installation)
+- [Requirements](#requirements)
+- [Connecting to the server](#connecting-to-the-server)
+- [Viewing cameras](#viewing-cameras)
+  - [PTZ](#ptz)
+  - [`beta` Matrix zoom](#beta-matrix-zoom)
+- [Layouts](#layouts)
+  - [Multiple Layout](#multiple-layout)
+  - [Compact layout](#compact-layout)
+  - [Cycling](#cycling)
+  - [External streams](#external-streams)
+- [Open app from configuration file](#open-app-from-configuration-file)
+- [Events](#events)
+  - [Browse events](#browse-events)
+  - [Timeline of Events](#timeline-of-events)
+  - [Downloads](#downloads)
+
+## Overview
+
+The Bluecherry Client lets you watch live and recorded video from your Bluecherry server. It is a cross-platform application that runs on Android, iOS, Windows, macOS, and Linux.
+
+## Download, Installation
+
+Refer to [README.md](./README.md#download) for installation instructions.
+
+## Requirements
+
+You will need a Bluecherry server to use this application. You can buy a license from the [Bluecherry website](https://www.bluecherrydvr.com/).
+
+## Connecting to the server
+
+These steps will guide you through easily connecting to your Bluecherry server. You can add as much servers as necessary. The steps are similar for all platforms.
+
+`1.` Enter the hostname or IP address of the Bluecherry server. The default login and password for new installations is `Admin` and `bluecherry`. You can optionally click `Use default` to have this information automatically entered for you.
+
+![Connect to server](./screenshots/add_server/insert_credentials.png)
+
+Click `Next` to connect.
+
+`2.` You can optionally change some settings for the server, such as the streaming type, RTSP protocol, and rendering quality.
+
+![Apply server settings](./screenshots/add_server/apply_server_settings.png)
+
+You can optionally leave these as they are. Click `Finish` to add the server.
+
+`3.` If the server was successfully added, you will be able to see the server in the server list and view the cameras.
+
+![Server successfully added](./screenshots/add_server/server_added.png)
+
+Click `Finish` to close the process.
+
+## Viewing cameras
+
+After your server is added, you will be redirected to the camera list. You can view the live video from the cameras by clicking on them or by dragging them to the layout.
+
+![Drag and drop cameras](./screenshots/cameras/drag-to-add.gif)
+
+You can repeat this process or any camera or DVR that you have listed on the left side. Note: It’s possible to connect as many devices together as you need, and mix and match the videos in different layouts.
+
+## PTZ
+
+The PTZ feature allows you to control the pan, tilt, and zoom of a camera. To enable it, click on the `PTZ` button on the camera tile.
+
+> [!Note]
+> The PTZ feature is only available for cameras that support PTZ. If the camera does not support PTZ, the PTZ button will not be available.
+
+You can press and move the mouse to control the camera.
+
+![PTZ](./screenshots/cameras/ptz.gif)
+
+You can perform the following movements:
+
+- Pan: Press and move the mouse left or right.
+- Tilt: Press and move the mouse up or down.
+- Zoom: Scroll the mouse wheel up or down.
+
+The PTZ movements are scheduled and will be executed after the previous movement is completed. Depending on the speed of the internet connection, you can experience minor delays between the movements and the camera response.
+
+> [!Tip]
+> It is recommended to wait for the camera to complete the previous movement before performing another one, but scheduling multiple movements is possible.
+
+> [!Important]
+> PTZ zoom is not supported on mobile devices. See [this issue](https://github.com/bluecherrydvr/unity/issues/107).
+
+## [beta] Matrix zoom
+
+The matrix view is a feature that allows you to zoom into a camera inside a pre defined grid.  This is useful in the event you have one stream that provides a grid of cameras (4x4 for example). This works better for cameras with larger resolutions
+
+To enable it, go to `Settings` -> `Updates` -> `Beta Features` -> `Matrix view zoom`.
+
+![Matrix view](./screenshots/cameras/matrix-zoom.gif)
+
+## Layouts
+
+You can create layouts to organize the cameras. You can add cameras to the layout by dragging them from the camera list to the layout.
+
+### Multiple Layout
+
+The multiple layout allows you to view as many cameras as you want in a grid. The grid will adapt to the number of cameras you add.
+
+### Compact layout
+
+The compact layouts creates a 2x2 grid with sub 2x2 grids. This is useful for viewing a large number of cameras in a small space.
+
+### Cycling
+
+You can enable the cycling to change the layouts automatically at a given interval (defaults to 30 seconds). This is useful for monitoring a large number of cameras.
+
+![Cycling at each 5 seconds](./screenshots/layouts/cycle.gif)
+
+### External streams
+
+You can add external streams to the layout. This is useful for adding streams from other sources, such as webcams, IP cameras, or other Bluecherry servers.
+
+To add an external stream, click on the `Add external stream` tile and enter the stream URL:
+
+![Add external stream](./screenshots/layouts/external-stream.gif)
+
+> In the example above, we add a test video to the layout.
+
+External streams are added to the `External Stream` layout.
+
+## Open app from configuration file
+
+You can open the app from a configuration file. This is useful for opening the app from a web browser or from a file manager. The configuration file is a `.bluecherry` file that contains the devices data.
+
+Here is an example of a configuration file:
+
+```
+[stream]
+video = rtsp://demo.bluecherry.app:7002/live/1
+
+[videoscreen]
+fullscreen = false
+
+[audio]
+sound = true
+```
+
+- The `stream` section contains the video URL. The app will try to connect to this URL when it is opened.
+
+- The `videoscreen` section contains the fullscreen setting, which determines if the app should open in fullscreen mode or add the video to the layout.
+
+- The `audio` section contains the sound setting, which determines if the stream should have sound or not.
+
+You can open the app from the configuration file by double-clicking it and opening it with the Bluecherry Client.
+
+Additionally, you can add overlays to the video by adding the following sections to the configuration file:
+
+```
+[overlay]
+text = "This is overlay number threee"
+size = 24
+color = #000000
+opacity = 80
+show = true
+position_x = 10
+position_y = 30
+```
+
+- The `overlay` section contains the text, size, color, opacity, show, position_x, and position_y settings. The overlay is persistent and will be shown on top of the video.
+
+- The `position_x` and `position_y` determines the position of the overlay on the video, being `0` the top-left corner of the video.
+
+The overlay can be edited from within the app:
+
+![Edit overlay](./screenshots/cameras/stream_configuration_file.png)
+
+Press `Finish` to add the stream to the layout.
+
+## Events
+
+The events section allows you to view the events that were recorded by the server. You can view the events by clicking on the `Events History` tab.
+
+### Browse Events
+
+Select the camera you want to view the events and click on the `Filter` button. You can filter the events by date range.
+
+![Events History](./screenshots/events/events-history.gif)
+
+### Timeline of Events
+
+The timeline of events allows you to view the events in a timeline. This is useful for quickly finding events. You can filter the events by date.
+
+![Timeline of Events](./screenshots/events/timeline-of-events.gif)
+
+> [!Note]
+> You can only view 6 cameras at the same time in the timeline of events.
+
+> [!Tip]
+> Use the mouse scroll wheel to zoom in and out of the timeline.
+> Use the arrow keys to move the timeline forward and backward.
+
+### Downloads
+
+You can download the events by clicking on the `Download` button. To see the downloaded events, click on the `Downloads` tab.
+
+![Downloads](./screenshots/events/download.gif)
+
+> [!Tip]
+> You can choose the download location in the Settings. The default download location is the `Downloads` folder.