-----------------------
 README (CutterFF 1.3)
-----------------------

Welcome to 'CutterFF', a small program for cutting videos using
'FFmpeg' and 'GTK+'. It is easy to use and fast, since it do not
decode and encode the streams, instead it only copy them.

You can read informations about configuring, compiling  and installing
this package in the file 'INSTALL', about some informations about running
it right here.


0. Launching
------------

You can start 'CutterFF' with some command line options:

 -v --version
   Display the program version and exit.

 -h --help
   Display a help message and exit.

 -l --log[level]=LOGNAME
   Write 'FFmpeg' messages to the console. May be useful, if you have
   problems with a video.

 -x --threads=NUM
   Set the number of threads used for 'CutterFF' and 'FFmpeg'. If NUM
   is less than zero or NUM is one, multi-threading is disabled. If NUM
   is zero or NUM is "auto", the automatic detection is enabled, else
   NUM will be the number of threads, limited by the number of CPUs.
   If 'CutterFF' freezes while opening a file or displaying a frame,
   you should run 'CutterFF' with multi-threading disabled!

 --locale=[C|de_DE]
   Set the locale to another than the default.

 --nls-dir=DIR
   Set the folder where the translation files can be found. This might
   another place than the compiled in (e.g. --nls-dir=/home/my/locale)


1. File
-------

1.1 Open
--------
A dialog lets you selecting a file. On the bottom right you can select
the desired file extension, so only this files will be shown. Click
on the file, and then of 'Ok', and this file will be opened. However,
some of the following errors are possible:
  "Couldn't open the input file"
    The file or folder was not found, you do not have the permission
    to read this file, or this file is not valid.
  "Couldn't find stream information"
    Stream informations about e.g. codecs and duration were not found.
  "No video stream found"
    This file do not have a video stream.
  "No video codec found"
    Look at 'Help->FFmeg' for the supported codecs.
  "Cannot get the frame duration"
    The duration of a single frame (picture) could not be determined.
  "Cannot get the gop size"
    This video is too short.
  "The picture type of the frame is unknown!"
    The decoder does not set the picture type (like 'libopenh264')
With the button 'Filter->Add' you can add a file extension (e.g. 'flv'),
if you are missing this one. Up to 10 extensions are possible.
The button 'Filter-Remove' shows you a list with the extionsions you
have added. Select the line of the extension you wish to remove, and
click 'OK'.
The dropdown menu 'HW-acceleration' lets you choose a hardware device.
If moving the mouse over this menu a tooltip appears and displays all
supported codecs of each device. But note that is only the support of
'FFmpeg', and maybe decoding with the selected device on the current
platform is not possible. If so, the decoding will be done by software,
and one of the following messages is written to the log window:
  "Could not find a hwaccel pixel format!"
  "Failed to get a hwaccel pixel format!"
  "Could not allocate hwaccel context!"
If hardware decoding works, it is possible that some frames of the
output are damaged. In this case, open the file again with another
(or no) device, else 'CutterFF' may crash!

1.2 Save
--------
See '7. Saving a video'.

1.3 Save image
--------------
The picture which is currently displayed will be saved. In the dialog
 you may change the filename, the folder and the dimensions of the
 image.
If changing the width and/or the height, and 'Keep aspect ratio'
 is set, the  resulting dimensions may differ.
If changing only the width or the height, only the other (unchanged)
 dimension will be changed.
If changing both, and the computed width is larger than your prefered
 width, then the prefered width keep unchanged, and the height will be
 computed. Else the height keep unchanged, and the width will be computed.
The option 'Gray' converts the image a black and white (grayscale)
 picture. This may not work with all encoders.
The dropdown menu 'Format' lets you choose the type of the image which
 should be saved. The matching extension will be appended to the filename.
It is possible that not all supported formats are shown, but with the
 extension of the filename you can select a format not listed here
 (e.g. 'myimage.tiff' > 'TIFF').
If 'Format' is 'Auto' and saving fails, select the format and try again.

1.4 Close
---------
The input file will be closed, and the undo, redo and cutpoint lists
will be cleared.

1.5 Info
--------
'FFmpeg' shows you some information about the streams containing the
input file, the duration, bitrate, frames per second, and so on.

1.6 Save rc file
----------------
The current settings, which are the window size, the options, the used
directories, the added extensions for the file dialog, and the keys for
the menu entries will be stored. This also will be done if the program
exits.
If you don't like this, disable the check menu 'Options->Save rc on exit'.
Save the rc file, and your settings won't be overwritten in the future.

1.7 Quit
--------
Use this if you lost interrest.


2. Edit
-------
This menu contains several entries to prepare your copy.

2.1 Undo
--------
The previous action, which is add or remove a cutpoint, will be undone.

2.2 Redo
--------
An action, which was undone, will be redone (add or remove a cutpoint
again).

2.3 Load list
-------------
Loads a list containing cutpoints. If a cutpoint is already asssigned, or
the frame for it cannot be found (the video actually loaded does not
contain a frame with this timestamp), a dialog box will tell you that one
or more points were discarded.
If you have set some cutpoints (which are not saved yet) and try to load a
list, you will be asked first if you want to add the list to the existing
cutpoints.

2.4 Save list
-------------
Saves the current cutpoints. Note that different decoders may have also
different values (like 'qsv'). If open the video with another decoder
and loading the saved cutpoints again, 'Cutterff' tries to adjust these
values, which mostly seems to be okay.
However, the best is to keep the same decoder!

2.5 Clear list
--------------
Removes all cutpoints. You will be asked first if you really want this,
so you can stop it. However, clearing the list can be undone.

2.6 Add
-------
Adds the current video position to the cutpoint list and clears the redo
list. You can set cutpoints wherever you want. The cutpoints work as
'start-stop-start-stop-...' and so on. The bar showing you red and green
areas tells you which parts of the video will be written to disk. The
green parts will be written, the red ones not.
To add a cutpoint you can also use the '+'-button at the bottom of the
window.

2.7 Remove
----------
Removes the current video position from the cutpoint list and clears the
redo list. To remove a cutpoint you have to go to this picture. You can
use the 'Home'- or 'End'-keys, which jumps to the previous/next cutpoint.
To remove a cutpoint you can also use the '-'-button at the bottom of the
window.

2.8 Goto
--------
A submenu displaying all cutpoints. Selecting one of them will jump to
this video position. The settings of 'Key/I/P-Frame' (see below) will be
ignored.

2.9 Program
-----------
If the file contains several programs, you can choose the desired one
from a list by clicking on it.


3. Options
----------

3.1 Keyboard
------------
Opens a dialog which lets you assign keys to the menu entries. Select
a line and press your prefered keys (e.g. 'Cntrl'+'Q'). To clear an
entry type 'Backspace'.

3.2 Key-Frame
-------------
As mentioned above, you can set cutpoints wherever you want. But in
general it is a good idea that each start point is a 'Key-' and/or
'I-Frame' (I think that both are the same). Enabeling this option will
cause that 'CutterFF' only jump to this frame type (if no others are set).
Maybe the choosed decoder do not mark frames as 'Key-Frames'. If so, all
'I-Frames' are treated as 'Key-Frames'!

3.3 I-Frame
-----------
See '3.2 Key-Frame'.

3.4 P-Frame
-----------
Each stop point (not the last one) should be either a frame type like
above or a 'P-Frame' ('hevc' always Key- and/or I-Frames, but test it out).
Setting the cutpoints to other frame types (B-Frames) may produce some
ugly looking pictures at this position! Enabeling this option will cause
that 'CutterFF' only jump to this frame type (if no others are set).
Notice: some videos do not have P-Frames, so if after some seeking no
frame was found, the video position will not be changed!

3.5 Cursor
----------
To inform you about that the program is busy, the cursor is changed as
long as the decoding is in progress. If your computer is fast enough and
the flickering is annoying you, disable it.

3.6 Overwrite
-------------
Disable the warning if a file already exists.

3.7 Delete copy on error
------------------------
If copying a file and an error occurs, the copy will be deleted. If
you want to keep this file, disable this option.

3.8 Beep
--------
Play a sound if an error occurs.

3.9 Save rc on exit
-------------------
See '1.5 Save rc file'.

3.10 Log ...
------------
Opens a window and writes 'FFmpeg' generated messages into it.
If 'CutterFF' has been launched with the option '-l' or '--log[level]',
the output will be redirected from the console to the window. Selecting
'Log->quiet' will print the messages on the console again.
Clicking with the right mouse button on the log window displays a popup
menu. Selecting the entry 'Color ...' opens a dialog, which lets you
choose the text and background color.
Note: any level above 'error' may throw a lot of messages and slow down
the program. If opening a file, as long as the the progressbar is not
visible it is possible to close the window, which makes opening faster.


4. Help
-------

4.1 FFmpeg
----------
Informs you about the formats, codecs, and bitstream filters which are
supported by the 'FFmpeg' libraries 'CutterFF' is using.

4.1 CutterFF
------------
Shows you the buttons and keys used for navigation.

4.2 About
---------
Version and licence.


5. Popup menu
-------------
Some menu entries mentioned above are also available with a popup menu.
This will be shown with a right mouse click or pressing 'Shift+F10'
on the keyboard.


6. Navigation
-------------
With the buttons at the bottom you can go back or forward. The keys 'left',
'right', 'up', 'down', 'page up', 'page down', 'home' and 'end' can also
be used. Pressing the shift key (or using the right mouse buttton instead
of the left) will increase the time. Have a look at 'Help->CutterFF' for
details ...
If jumping to the previous/next cutpoint with the keys 'home' or 'end' the
settings of 'Key/I/P-Frame' (see above) will be ignored.
The frame counting starts from zero, but sometimes the first frame which
will be displayed is some frames later. In this case the frames before
it cannot be decoded.
The frame number was computed by the current timestamp devided by the frame
duration. If the video contains frames with different durations (e.g. some-
times only the half), the computed number may incorrect, and going a frame
back or forward may display the same number.
The time which is needed for displaying the frame you wish to show as next
depends on the video stream and your computer. If your computer is not
fast and the video has a stream like 'hevc', this may take some seconds.
If the video you have loaded contains broken timestamps, it may not be
possible to jump to another frame, then try with other buttons or keys.
But sometimes nothing will help, and you cannot leave this frame. In this
case save the whole file (remove all cutpoints), enable 'Create timestamps
from packet duration' for 'Video', 'Audio' and 'Others', and open the copy.
Maybe this works.


7. Saving a video
-----------------
The menu entry 'File->Save' shows you a dialog box, which lets you perform
the final settings. The main options may often used, below of them is a
field called 'Extra' with the tabs 'General', 'Video', 'Audio' and 'Others'.
Use the entries for some fine tuning, but in most cases you won't need this.

7.1 Main
---------
Select the basic properties.

7.1.1 File name
---------------
Choose the filename and the desination. Type it in the field at the top or
click on the button right of it, which opens a file selector.

7.1.2 Streams
-------------
Below you can see a list of the streams your video file contains.
Select the stream you want for the output file and click on '>' (multi
selections are okay). To reorder the streams, select one and click on the
'Up' or 'Down' button (multi selections are okay).

7.1.3 Shortest duration
-----------------------
If the duration of the output file should be equal to the shortest duration
of the selected streams, set this option.

7.1.4 Stream sync
-----------------
Normally the stream copying is started with the video stream, and stopped
with it. If e.g. the audio stream is shifted a little bit, the output may not
be lip-sync. If this option is enabled, the streams are copied independend of
the video stream and may solve this problem.
Enabling this option is only possible if at least one cutpoint is set (see
Soft cut).

7.1.5 Soft cut
--------------
If a start frame (left of the green bar) is not a 'Key-' and/or 'I-Frame',
this frame and some of the followings will be damaged after copying. With
soft cutting the frames at the cutpoints will be decoded, and then encoded
again. Now the frames got the right references to the previous and the
following frames, and the cut is smooth and well looking.
For proper de- and encoding, the space between cutpoints should be at least
two GOPs (Group Of Pictures - frames from a 'Key-frame' till the next).
If the start frame of the video (the very first frame) is a 'Key-frame',
soft cutting will be ignored, but the following cutpoints will be de- and
encoded, regardless of the picture type of the start frames.
The aspect ratio the encoder will use is the ratio of the currently displayed
picture. If the video contains different aspect ratios, then display a frame
in the window which has the ratio your video should have!
Some videos (mpeg-4) may need one of the bitstream-filters 'h264_mp4toannexb'
or 'hevc_mp4toannexb'. Without this filter, the output will be damaged, and
looks worse than hard cutting. If one of these filters is required will be
detected automatically, and used. But note: 'CutterFF' supports only one
bitstream-filter per stream, so if another video filter is enabled, this
takes precedence.
As long as the de- and encoding is working, the numbers of the actual de- and
encoded frames are displayed in the progressbar. If the loglevel is set to at
least 'warning', also some messages may be displayed.
Note: selecting the position of the cutpoints may be important. If the stop
frame is too close at the end of a GOP (Key-frame), this may include some
following frames, which - if the scene has changed - are unwanted. This is
also true for the start frame too close at the start of a GOP and including
unwanted previous frames. So you should make a short test and, if the result
is not okay, moving the cutpoints one or two frame(s) for or back, and try
again.
At least, enabling this option is only possible if at least one cutpoint is
set. The number of GOPs between start and cutpoint must be at least two. If
there are more cutpoints, this is not neccassary. And - also important - the
needed encoder must be available in 'FFmpeg'.
If a hardware encoder was choosed, maybe encoding is not possible. If so,
the encoder is supported by 'FFmpeg', but not by the current platform.
Some encoders may not support interlaced video (like 'vaapi') or the aspect
ratio. Have a look at the log-window and the saved video.
If the video was opened with a 'qsv'-decoder, than encoding is disabled.
Moving the mouse over the softcut-menu a tooltip appears and displays all
available encoders. For encoding open the video with another decoder!
WARNING: if using softcut with a 'qsv'-encoder, then loading the saved file
with a 'qsv'-decoder, moving the slider from left to right and back and so
on, 'CutterFF' may ends in an infinite loop. Then you must kill 'CutterFF'!

7.1.5.1 Both GOPs
-----------------
The GOP (or remaining frames if not starting with a 'Key-frame') which will
be encoded are the ones at the start frame. With this option also the last
GOP of the previous stop frame (right of the previous green bar) will be
encoded. So this connects the frames at stop and start, and their references
to the other frames. But normally this option shouldn't be neccassary, and
sometimes the result is worse than without it.

7.2 General
-----------
For all streams.

7.2.1 Keep start timestamps
---------------------------
Normally the timestamps are reset and starts from zero. If video and audio
of the copy are not synchron, you may try again with setting this option.

7.2.2 Format
------------
This dropdown menu lets you choose the muxer for the output file. The codecs
which one muxer supports will be shown in braces. Some muxer will only be
useable for audio, other for video, so select the output streams accordingly.
The matching extension will be appended to the filename.
The setting 'Auto' is the same as the input format or, if you changed
the extension of the filename, the format which is matching this extension
(e.g. '.ts' to '.mp4' will change the muxer from 'mpegts' to 'mp4'). Any
other settings will ignore the filename extension and forces muxing to the
selected format. Usefull if you extract an audio stream and write it to this
format (e.g. 'mp3'). Or you change the format for 'mpegts' to 'mp4', the video
stream is 'hevc', and the audio stream is 'aac'.
But this will not always work: if the format do not like a stream coding you
will get an error like 'Header write failed'.

7.3 Video
-----------
For video only.

7.3.1 Create timestamps from packet duration
--------------------------------------------
This option may usefull when saving the file ends up with an error message
like 'av_interleaved_write_frame failed'. Lauch 'CutterFF' from a console with
the option '--loglevel=info', or open the log-window, and try again. If the
'FFmpeg' message written to the console (log-window) contains
  'non monotonically',
enable this option. The timestamps will be increased with the packet duration,
and ignoring the original timestamp. Therefore it may not work always, video
and audio are not synchron.

7.3.2 Adjust broken timestamps
------------------------------
If the above option do not work (video and audio are not synchron), you may
try this. If a timestamp is less or equal than the previous one, the timestamp
will be set to the previous timestamp plus the previous packet duration.
This is only possible if above option is not selected.

7.3.3 Bitstream Filter
----------------------
The dropdown menu lets you choose a bitstream filter for video streams. If
it works only with a special codec, this will be shown in braces. The listed
filters works with all available streams, not only the selected ones. If the
list is empty, either there is no stream for this media type, or no codec was
found.
For more informations about the filters have a look at the manual page
'ffmpeg-bitstream-filters'.

7.4 Audio
---------
For audio only.

7.4.1 Create timestamps from packet duration
--------------------------------------------
See '7.3.1 Create timestamps from packet duration'.

7.4.2 Adjust broken timestamps
------------------------------
See '7.3.2 Adjust broken timestamps'.

7.4.3 Bitstream Filter
----------------------
I have used it only for changing the format from 'mpegts' to 'mp4', which
requires the filter 'aac_adtstoasc' to fix the bitstream. Besides these
are audio filters only, it is the same as '7.3.3 Bitstream Filter'.

7.5 Others
----------
For streams which are not video or audio. I haven't test this yet.
See '7.2 Video'.


8. Translations
---------------
If there is not a translation in your language available, but you would like
to have it, just make it at your own.
Change into the 'po' directory and type 'cp cutterff.pot mylang.po'.
Open 'mylang.po' with an editor of your choice and fill the 'msgstr' lines
with your translation. Put in the header your name, character set and remove
the fuzzy line. Save this file and open the Makefile. Look for MOFILES, POFILES
and POXFILES. Insert 'mylang.mo', 'mylang.po' and 'mylang.pox'. Save your work
and type 'make'. If there are no errors, get back and type 'make install-strip'.

If you are changing messages in any source files, you can type
  'rm cutterff.pot'
  'make cutterff.pot'
and then
  'make pox'
Now you have to modify all the pox files with the new translations, then
type 'make mv', followed by a 'make', which will update all mo files.

----------------------------------------------------------------------------

I hope that you will like this program. Have a lot of fun ...
Harald

Harald F&ouml;rster <harald_foerster@users.sourceforge.net>

/* EOF */
