--- /dev/null
+BSD 3-Clause License
+
+Copyright (c) 2021, Urban Wallasch
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--- /dev/null
+# Ffpreview
+
+Ffpreview is a python script that acts as a front-end for ffmpeg to
+generate interactive thumbnail previews for video files.
+
+
+## Requirements
+
+To run `ffpreview.py` you will need Python version >= 3.7 installed,
+plus the PyQt5 python bindings for Qt5.
+
+As a hard requirement, ffpreview relies on the `ffmpeg` program to
+generate the still frame thumbnails. To make full use of the interactive
+aspects you will need a video player application that can be started from
+the command line. The `mpv` player is highly recommended, as it readily
+accepts all options passed by ffpreview. Other video players (like e.g.
+`vlc`) may only provide slightly degraded functionality.
+
+Additionally, ffpreview will use `ffprobe` (if available) to perform the
+initial video file analysis, but will gracefully fall back to `ffmpeg`
+for that purpose too, should `ffprobe` fail.
+
+**NOTE: Ffpreview has only been tested to work on Linux.**
+
+
+## Configuration
+
+All options available from the command line (see below) as well as the
+invocations used to start external programs can be specified in the
+configuration file, see `ffpreview.conf.sample`.
+
+
+## Usage
+
+Running `ffpreview.py -h` will print the following help text:
+
+```
+usage: ffpreview.py [-h] [-c F] [-g G] [-w N] [-t P] [-f] [-r] [-i] [-n N]
+ [-N F] [-s F] [-C S] [-S T] [-E T] [-v] [--version]
+ filename
+
+Generate interactive video thumbnail preview.
+
+positional arguments:
+ filename input video file
+
+optional arguments:
+ -h, --help show this help message and exit
+ -c F, --config F read configuration from file F
+ -g G, --grid G set grid geometry in COLS[xROWS] format
+ -w N, --width N thumbnail image width in pixel
+ -t P, --tmpdir P set thumbnail parent directory to P
+ -f, --force force thumbnail and index rebuild
+ -r, --reuse reuse filter settings from index file
+ -i, --iframe select only I-frames (default)
+ -n N, --nskip N select only every Nth frame
+ -N F, --nsecs F select one frame every F seconds
+ -s F, --scene F select by scene change threshold; 0 < F < 1
+ -C S, --customvf S select frames using custom filter string S
+ -S T, --start T start video analysis at time T
+ -E T, --end T end video analysis at time T
+ -v, --verbose be more verbose; repeat to increase
+ --version print version info and exit
+
+ The -C, -i, -N, -n and -s options are mutually exclusive. If more
+ than one is supplied: -C beats -i beats -N beats -n beats -s.
+
+ The -r option causes ffpreview to ignore any of the -w, -C, -i
+ -N, -n and -s options, provided that filename, duration, start
+ and end times match, and the index file appears to be healthy.
+
+window controls:
+ ESC, Ctrl+Q quit application
+ Ctrl+G adjust window geometry to optimal fit
+ Mouse-1 open video at clicked position in paused state
+ Shift+Mouse-1 play video starting at clicked position
+ Mouse-2 open the context menu
+```
+### Examples
+```
+$ ./ffpreview.py my_video.mp4
+
+$ ./ffpreview.py -t ~/scratch -w 256 -g 8x4 -N 10 some_movie.mkv
+```
+
+## License
+
+Ffpreview is distributed under the Modified ("3-clause") BSD License.
+See `LICENSE` file for more information.
+
+----------------------------------------------------------------------
Copyright 2021 Urban Wallasch <irrwahn35@freenet.de>
-BSD 3-Clause License
-
-Copyright (c) 2021, Urban Wallasch
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
- list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
- this list of conditions and the following disclaimer in the documentation
- and/or other materials provided with the distribution.
-
-* Neither the name of the copyright holder nor the names of its
- contributors may be used to endorse or promote products derived from
- this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Ffpreview is distributed under the Modified ("3-clause") BSD License.
+See `LICENSE` file for more information.
"""
_FFPREVIEW_VERSION = '0.2+'
projects / ffpreview.git / commitdiff