172 lines
12 KiB
Markdown
172 lines
12 KiB
Markdown
# Talked
|
||
|
||
Call recording for Nextcloud Talk
|
||
|
||
## How it works
|
||
|
||
Talked works by launching a Firefox instance in a virtual framebuffer, joining the Talk call, and then recording whatever is on screen using FFmpeg. The call is in fullscreen and using the speaker view. During your call, the recording user will be visible while the recording is active. Some custom CSS is added to the page so, when recording in speaker view, the recording user is completely hidden from the recording itself.
|
||
|
||
## Hardware requirements
|
||
|
||
The default configuration has been designed to run on a 2 core / 2 GB ram VPS. If you have beefier hardware and would like better recording quality, then you can play around with the settings to increase the resolution, crf and encoding preset.
|
||
|
||
## Current limitations
|
||
|
||
These are the current limitations of Talked. They will be worked on for future releases.
|
||
|
||
* Only one recording can be active at a time.
|
||
* The HTTP API is design to be single threaded and only handle one request at a time.
|
||
* Recording only works with rooms that are public (Allows guest access through a link).
|
||
* The recording is set up to use speaker view, but if the recorder is started while a screen share is active and then the screen share is ended the recording will use grid view from that point on. This mainly means the recording user will be visible in the recording. The recording user is completely hidden from the recording when using speaker view.
|
||
|
||
## Installation
|
||
|
||
These instructions are made for Ubuntu 20.04, but they should hopefully be fairly easy to use for other distros, if you're familiar with them. These instructions are mainly intended to help you get started and should be adapted to your needs.
|
||
|
||
First let's install the required dependencies
|
||
```
|
||
sudo apt install build-essential python3 python3-dev python3-venv python3-wheel firefox-geckodriver pulseaudio xvfb ffmpeg
|
||
```
|
||
|
||
Then let's create an unprivileged user to run Talked with.
|
||
```
|
||
sudo useradd --system --shell /bin/bash --home-dir /opt/talked --create-home talked
|
||
```
|
||
|
||
Then change to the newly created user with `sudo su talked` as it will be easier to set up the virtual env. To set up the virtual env run the following
|
||
```
|
||
python3 -m venv /opt/talked/talked
|
||
```
|
||
Then activate it
|
||
```
|
||
source /opt/talked/talked/bin/activate
|
||
```
|
||
And install talked and uwsgi
|
||
```
|
||
pip3 install talked wheel uwsgi
|
||
```
|
||
|
||
Now let's create the config file at `/opt/talked/config.toml`. The only required parameter is `base_url` but it might be useful to change some of the other options as well. You can see a list of the available options further down. The most basic config would look like this:
|
||
```
|
||
base_url = "https://nextcloud.example.com"
|
||
```
|
||
|
||
Talked uses the environment variable `TALKED_CONFIG_PATH` to find the config file. The easiest way to set it is to put it in the systemd service file used to start the talked server.
|
||
|
||
Further down you can find an example systemd unit file that can be used to start and stop the Talked server. You can use the following command to test the Talked server. Please note the command binds to localhost, you can change it to whatever you need.
|
||
```
|
||
uwsgi --http 127.0.0.1:5000 --master --manage-script-name --mount /=talked.main:app
|
||
```
|
||
|
||
It's recommended to set up Nginx or Apache in front of uwsgi to handle TLS and HTTP Basic auth. Currently, there isn't any authentication system built into the Talked server, so it's recommend to set up HTTP Basic auth. It's also recommended to only allow requests from your Nextcloud server to the Talked server, this can either be configured in your firewall or web server config.
|
||
|
||
When using uwsgi behind a webserver it's recommended to use the `--http-socket` option instead to connect over a unix socket. To do so create the folder `/var/run/talked` with the appropriate permissions for your setup and then run talked using a command like below:
|
||
```
|
||
uwsgi --http-socket /var/run/talked/talked.sock --master --manage-script-name --mount /=talked.main:app
|
||
```
|
||
|
||
You can have a look at the following instructions for nginx: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/
|
||
|
||
## Configuration options
|
||
|
||
| option | default | description |
|
||
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| base_url | "" | The base URL of your Nextcloud instance. Should include the http / https and have no leading slash. |
|
||
| log_level | "warning" | The log level that should be used. |
|
||
| recording_dir | "." | The directory where the recordings should be stored. |
|
||
| finalise_recording_script | "" | Script to run after a recording has finished. The absolute path to the recording will be passed as an argument to the script. |
|
||
| grid_view | false | If set to true the recording uses grid view instead of speaker view. The recording user is partially hidden in that it isn't visible but the empty slot in the grid view is still there. |
|
||
| video_width | 1280 | The virtual display and recording width in pixels. |
|
||
| video_height | 720 | The virtual display and recording height in pixels. |
|
||
| color_depth | 24 | The color depth to use for the virtual framebuffer. |
|
||
| framerate | 30 | The framerate that should be used for the recording. |
|
||
| audio_only | false | Specify whether audio only recording should be the default |
|
||
| audio_codec | "wave" | The audio codec to use for audio only recordings. The following options are supported: wave, flac, opus, aac and mp3. The audio codec used for video recordings is currently determined by the chosen video codec. |
|
||
| audio_bitrate | "160k" | The default audio bitrate to use. This will be used as a fallback if a codec specific audio bitrate hasn't been set. Please note that some codecs supports higher bitrates than others. |
|
||
| audio_aac_bitrate | "" | Bitrate to use for AAC |
|
||
| audio_mp3_bitrate | "" | Bitrate to use for mp3 |
|
||
| audio_opus_bitrate | "" | Bitrate to use for opus |
|
||
| audio_thread_queue_size | 128 | |
|
||
| video_codec | "x264" | The video codec to use for the recording. Currently only x264 is supported. |
|
||
| crf | 25 | The crf to use for the H.264 encoding. |
|
||
| video_thread_queue_size | 32 | |
|
||
| encoding_preset | "veryfast" | The encoding preset used for the H.264 encoding. |
|
||
| encoding_threads | 0 | How many threads to use for the encoding. 0 is auto. |
|
||
|
||
## Development setup
|
||
To setup a dev environment for coding, clone the repository and then run `make dev-setup` to setup a virtual environment with the needed dependencies.
|
||
|
||
For testing, a docker container is included in the repository as Talked only works on Linux. To build and run the container make sure you have docker installed for your OS. Then build the docker container using this command:
|
||
```
|
||
make dev-build
|
||
```
|
||
|
||
Then start the container using this command, it will take over the current terminal you have open. The command will start the docker container giving you a bash shell and a user with the same ID as your user on the host. The root of this project will also be passed through to the container in the /home/talked/talked folder. The container will get removed when you exit out of it, so you don't manually have to do it.
|
||
```
|
||
make dev-run
|
||
```
|
||
|
||
When you enter the container you will be placed in the /home/talked/talked folder, to get started first install the python dependencies using poetry.
|
||
```
|
||
poetry install --no-dev --no-root
|
||
```
|
||
|
||
Then create a config file called `config.toml` in the root of the project which contains the base URL for your Nextcloud instance. Below you can see the boilerplate:
|
||
```
|
||
base_url = "https://nextcloud.example.com"
|
||
```
|
||
The config file location is controlled by the `TALKED_CONFIG_PATH` env var and by default, in the container, it is set to the root of the project folder.
|
||
|
||
Now you can run the program either using:
|
||
```
|
||
poetry run python3 -m talked --host 0.0.0.0
|
||
```
|
||
Or by entering the virtualenv and then running the program. We bind the internal server to all interfaces so it can be easily access outside the docker container:
|
||
```
|
||
poetry shell
|
||
|
||
python3 -m talked --host 0.0.0.0
|
||
```
|
||
|
||
Lastly remember to join the call before starting the program, as it will only join if there is a call in progress.
|
||
|
||
## Example systemd service
|
||
|
||
```
|
||
[Unit]
|
||
Description=talked
|
||
Requires=network.target
|
||
After=network.target
|
||
|
||
[Service]
|
||
WorkingDirectory=/opt/talked
|
||
User=talked
|
||
Group=talked
|
||
|
||
RuntimeDirectory=talked
|
||
|
||
Environment=TALKED_CONFIG_PATH=/opt/talked/config.toml
|
||
|
||
ProtectSystem=full
|
||
ProtectHome=true
|
||
ProtectKernelTunables=true
|
||
ProtectKernelModules=true
|
||
ProtectControlGroups=true
|
||
PrivateTmp=yes
|
||
NoNewPrivileges=yes
|
||
|
||
SyslogIdentifier=talked
|
||
StandardOutput=syslog
|
||
StandardError=syslog
|
||
|
||
ExecStart=/opt/talked/talked/bin/uwsgi --http-socket /var/run/talked/talked.sock --die-on-term --master --manage-script-name --mount /=talked.main:app
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
## License
|
||
|
||
This program is licensed under the AGPLv3 or later.
|