-----------------------
 README (CutterFF 0.8)
-----------------------

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]
   Write 'FFmpeg' messages to the console. May be useful, if you have
   problems with a video.

 --locale=[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.
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'.

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.

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).

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 since version 0.5 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 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. First you can 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.
Below you can see a list of the streams that contains your video file.
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).
If the duration of the output file should be equal to the shortest duration
of the selected streams, you may set the option 'Shortest duration'.
Next 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 General
-----------
For all streams.

7.1.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.1.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.2 Video
-----------
For video only.

7.2.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.2.2 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.3 Audio
---------
For audio only.

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

7.3.2 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.2.2 Bitstream Filter'.

7.4 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 */
