Snapshot is an application that allows you to view a video and record it as a
set of snapshots. This is useful when you want to make a time-lapse of a video.
The application has a graphical user interface to view the video and a command
line interface to configure the application. It can also be configured using a
configuration file. The project is written in C++ and uses
Qt6. For more information, run snapshot --help, or
continue reading.
In short, snapshot contains the following features:
- List the available cameras.
- Display a video stream:
- using RTSP, UDP or HTTP.
- from a file.
- from a (built-in) camera.
- Record a video in a set of snapshots at a given interval and duration.
- Configure the application using a configuration file.
- Has a command line interface.
- Runs on linux (including raspberry pi).
- 64 bit Linux systems only
- glibc
$\geq$ 2.35 (when using the tarball) - X11, Wayland are supported. EGLFS is support is added, but not tested.
- Tested on Ubuntu 22.04, Arch linux and Raspberry Pi OS (bullseye).
The following sections explain how to install the project. You have two options: using the pre-built binaries. The easiest way is to use the pre-built binaries, i.e., the stand-alone tarball.
Requires that glibc
$\geq$ 2.35
This is the easiest way to install the application.
Go to the releases page and
download the latest tar.gz file. Extract the file using the following
command:
tar -xvf snapshot-<version>-Linux.tar.gzThis creates a snapshot-<version> directory with the following structure:
snapshot-<version>
├── runtime/
└── snapshotthe runtime directory contains files you should not touch. The snapshot
script is the one that you should use to interact with the application. For
example:
./snapshot-<version>/snapshot --helpwill print the help message. For convenience, you can place the
snapshot-<version> folder anywhere you like, and create a symlink to the
snapshot script in a directory that is in your PATH. For example:
ln -s /path/to/snapshot-<version>/snapshot $HOME/bin/snapshothere it is assumed that the $HOME/bin directory is in your PATH.
Extra information about the tarball is provided in Development.
In this section, the steps to build the project from source are explained. In short:
- You can use the
setupscript to install the dependencies. - A static or shared Qt build can be selected.
- A Qt account is needed in order to use the
setupscript. - Using the
configurescript, the build can be configured.
Snapshot relies on the following dependencies:
| Dependency | Version |
|---|---|
| Qt6: base & multimedia | 6.6 |
| ffmpeg | 6.0, 6.1 |
| boost |
|
| spdlog |
|
Here, the Qt6 version is fixed. Other versions of ffmpeg, boost, and spdlog might work, but are not tested.
For building the project, the following dependencies are required:
Building the project was tested using
cxxopts and googletest are also dependencies, but they are included in the
project. The former as a header file in the 3rdparty directory, and the latter
is installed using cmake.
The
setupscript only supports Arch Linux and Ubuntu 22.04. If you are using a different distribution, you need to install the dependencies yourself.
The following sections explain how to set up the environment for building the project. Since you need a specific version of Qt6, it is recommended to use the online installer of Qt which is included in this project.
Using the local installer is recommended as it installs the correct version in a subdirectory of the project. This way, the system Qt version is not affected.
Do the following:
-
Clone the project:
git clone https://github.com/BartSte/snapshot
and
cdinto root directly the project (containing the.gitdirectory). -
Register a Qt account on the website of Qt.
-
Run the
login-qtscript with your credentials:./scripts/login-qt --pw <password> --email <email>
This creates a
qtaccount.inifile at~/.local/share/Qtwhich is used when downloading Qt. -
Run the
setupscript to install the dependencies:./scripts/setup
You can pass the
--static(default) or--sharedoption to the script, to build Qt as a static or shared library. The--staticoption results in a longer build time, when compared do--shared, as Qt and ffmpeg are built from source. The--sharedoption results in a less build time as pre built Qt and ffmpeg libraries are used. However, the--sharedoption results in more libraries (*.so files) that need to be installed on your system.Once, the script is done, you can find the Qt libraries in the
3rdparty/Qtdirectory (ffmpeg is included). If you choose the--sharedoption, you can also find the ffmpeg libraries in the3rdparty/ffmpegdirectory.
Ensure that the root of the project is your current work directory. Run the
configure script to configure the build:
./scripts/configureThis script creates a build directory containing the ninja build files. You
can pass -- -DDBUILD_TESTING=ON to the script to enable the tests. Here, all
arguments after the -- are passed to cmake directly.
Build the project by running the following command:
cmake --build ./buildThis creates the snapshot executable in the build/bin directory.
Install the project by running the following command:
sudo cmake --install ./buildThis will install the project in the /opt/snapshot directory. The /opt
directory is chosen as snapshot is a self-contained application. The installed
files tree is as follows:
/opt/snapshot
├── runtime/
│ └── libs, bins, and qt plugins
└── snapshotWhere snapshot is the entry point of the application. If you want to add the
snapshot executable to your PATH, you can create a symlink to
/usr/local/bin:
sudo ln -s /opt/snapshot/snapshot /usr/local/bin/snapshotOr you can add the /opt/snapshot directory to your PATH.
If you have no root access, you can install the project in you home directory by
using the --prefix option. For example, if you want to install the project in
the $HOME/opt/snapshot directory, you can run the following:
cmake --install ./build --prefix $HOME/opt/snapshotThis will install the project in the $HOME/opt/snapshot directory, instead of
the /opt/snapshot directory.
- TODO
The snapshot executable should be executed from the command line. The
following sections explain how to use the application. You can also run
snapshot --help to get more information.
By running the following command, a list of available cameras is shown:
snapshot --listthis outputs something like:
Index | Name | ID | Is Default |
0 | HP TrueVision HD Camera | /dev/video0 | true |which means that there is one camera available, with index 0, name HP TrueVision HD Camera, id /dev/video0 and is the default camera.
If we want to display a video stream from the default camera, we can run the following command:
snapshot --guiIf a camera is found, it will opens a window with the video stream from the default camera. You can also specify the camera to use. By doing:
snapshot --gui --camera "HP TrueVision HD Camera"This will display the video stream from the camera with the name that matches
the name given by the --list command in the previous section.
If we want to display a video stream from a file, we can run the following:
snapshot --gui --camera sample.mp4If we want to display a video stream from a URL rtsp://localhost:8090/stream,
we can run the following:
snapshot --gui --camera rtsp://localhost:8090/streamNote that we can feed the --camera option with a file, a URL or a camera
name. Lastly, the --timeout option can be used to specify how long the app
should be searching for a video at startup, or when the connection is lost. By
default, this is set to 30s.
When you want to record snapshots from a video stream, you can use the
--record option. For example, if we want to record a video stream from the
default camera, we can run the following command:
snapshot --recordThis will save snapshots of the default camera with the default values for the
--interval, --duration and --folder options, i.e., every second for 10
seconds, for an unlimited time, in the ./snapshot folder. Most likely, you
want to change these values. For example:
snapshot --record --interval 5 --duration 60 --folder /path/to/folderthis will save snapshots every 5 seconds for 60 seconds in the /path/to/folder
folder. If the folder does not exist, it will be created, as long as the parent
folder exists.
To ensure that the disk does not fill up the snapshots when you forget to stop
the recording, the --max-snapshots is set to 10e9 bytes (10 GB) by default,
which means that the recording will stop when the current session exceeds this
size.
Instead of using the command line options, a cnfiguration file can be used. By
default, the application looks for a file called config.json in the
$HOME/.config/snapshot directory. If no configuration file is found, the
application uses the default configuration which is equivalent to the default
values of the command line interface (see snapshot --help).
Below an example of a configuration file is shown that has the default values:
{
"gui": false,
"list": false,
"record": false,
"camera": "default",
"folder": "./snapshot",
"timeout": "30s",
"duration": "0s",
"interval": "10s",
"max-bytes": "10e9",
"loglevel": "warning",
"pattern": "[%Y-%m-%d %H:%M:%S.%e] [%l] [%s:%# @ %!] %v"
}Naturally, you can change the values to your liking. For example, by setting
the gui option to true, the application will open the gui by default. This
is equivalent to running snapshot --gui. Note that the command line options
override the configuration file options when they are given.
If you want to put your configuration file in a different location, you can
specify the location using the --config option:
snapshot --config "$HOME/some/other/location/config.json"Note that the ~ character and environment variables are expanded. Environment
variables must be specified using the ${VAR} or $VAR syntax.
By default, the logging level is set to warning. If we want to set the
logging level to debug, we can run the following command:
snapshot --log-level debug <other options>The following logging levels are available: trace, debug, info,
warning, error, and critical.
If you want to contribute to this project, you should start by reading CONTRIBUTING, and installing the project from source. This section provides information about: the tarball, the unit tests, and ways to debug the application.
Googletest and QTest are used for building the unit tests and the end-to-end
tests. To build the tests, the BUILD_TESTING option must be set to ON when
configuring cmake:
./scripts/configure --build_type Debug -- -DBUILD_TESTING=ONthis will use the Debug build type with the tests enabled. To run the tests,
run the following command:
ctest --test-dir ./buildAdditional information about the stand-alone tarball is provided here.
snapshotis an executable in the form of a bash script. This script:- sets the
LD_LIBRARY_PATHto thelibdirectory and runs thesnapshotbinary. - resolves the path to the script if it is referenced using a symlink.
- sets the
- the
runtimedirectory contains shared libraries and binaries that thesnapshotscript depends on. In case the project is built with the--sharedoption, theruntimefolder will also contain subdirectories with the libraries of the Qt plugins. Theruntimedirectory does not include the standardc/c++libraries (libc,libstdc++,libm,libdbm,libpthread) together with the dynamic linker as they are assumed to be present on the system. snapshot_testis an executable in the form of a bash script. This script is only present when the project is built with thecmakeoption-DBUILD_TESTING=ON. If so, when running thesnapshot_testscript, all tests are executed.
You can use one of the following ways to run the application with a video stream:
A sample video file is provided in the tests/static. It can be played using
the following command:
snapshot -g -c tests/static/sample.mp4This opens the gui and plays the sample.mp4 file.
If you have internet access, you can use the following command to play a video from a public http stream:
snapshot -g -c http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4This opens the gui and plays the video.
By running the following command, a video stream is published using the rtsp protocol:
./scripts/rtsp-stream tests/static/sample.mp4 rtsp://localhost:8090/streamThis stream can be viewed using the following command:
snapshot -g -c rtsp://localhost:8090/streamThis displays the video stream using the GUI.
Similar to running the rtsp stream, an udp stream can be published using the following command:
./scripts/udp-stream tests/static/sample.mp4 udp://localhost:8090This stream can be viewed using the following command:
snapshot -g -c udp://localhost:8090This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues, please report them on the issue tracker at: snapshot issues
Contributions are welcome! Please see CONTRIBUTING for more information. Also, read the section on Development for additional information.
On WSL2, if you encounter the following error:
Fontconfig error: Cannot load default config fileinstall fontconfig on your system as is describe on the website of Qt
Issues with your graphics card need to be resolved by the user itself, as this application has no control over it. The following pages from the arch wiki are very useful when you encounter issues with hardware acceleration: