March 26, 2023
------------------------------------------------------------------------------

The Zippy Clipper Linux Media Editor

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

Entry Boxes

The display of videos file anmes shown in the 12 Zippy Clipper entry boxes reflects the contents of the 'videos' directory. Please place copies of any video you want to work with in this directory. 

You may sort this list with the <Alpha Sort Dsc>, <Alpha Sort Asc>, <Date Sort Asc> or <Date Sort Dsc> buttons. You may drag/drop entries to other rows and you may drag/drop videos from other directories into these entry boxes. If you drag and drop a video from another directory into the entry list, the video does not move to the 'videos' sub-directory: it remains in it's original directory. The up/down arrow buttons next to each row move move an entry to the top (left click) or bottom (right click). The ? box shows properties of the video or audio entry.

Videos whose <select> boxes are checked, may be deleted with the <Delete Selected Videos> button. 


Video Processing

Video processing is very CPU intensive. This will result in the temperature of your CPU rising. You should monitor CPU temperature to insure that it is not overheating. There are several Linux CPU temperature monitoring apps available for this purpose. If your CPU is prone to overheating, you may be able to slow the CPU clock. See "CPU Frequency Scaling Monitor", for example.


Extracting a Video Clip from a Larger Video

1. Hit the <Play> button next to the video file name entry box. The video will begin to play.

2. When the video player gets to the starting point of the section you want to extract, click the <Mark Clip Start> button.

3. When the video player gets to the end point of the section you want to extract, click the <Mark Clip End> button.

4. Click the <Let Zippy Clip It> button. A command will be issued to ffmpeg to extract the section selected. You will see a command window showing ffmpeg progress. When done, the progress window will disappear and the new video file name will appear in the topmost entry box.

Notes:

1. You can use <Playback Control> for slow motion to approach the start/end point slowly.

2. You can use <Frame Advance> to move forward frame by frame. Due to restrictions in VLC, <Frame Advance> only moves forward.

3. You can advance/retreat by 1, 2 or 4 seconds. If you retreat in pause mode, you must click <Frame Advance> to see the updated video frame (VLC limitation).

4. You may drag the slider bar forward or backward to move through the video.


Cropping A Video

After selecting a video to play and identifying the area of the video as above, adjust the <Crop Control> sliders to select the portion of the image that will be extracted. Click <Let Zippy Do It> when done. The section of video selected will be extracted and cropped. A progress window will appear. When successfully finished, a new video entry will appear at the top of the file entry boxes.

Notes:

The cropped video will have a different geometry than the original. Some geometries may not play correctly on some players. If you want to combine cropped videos, you need to standardize their geometries using the <Standardize> box options.

Video Filters

Each video filter can work on one or more videos at a time. The videos to be processed are selected by checking the <Select> boxes next to the video entries. Not all filters work in Windows WSL2. The filters are:

<Video>  Alter the brightness, contrast or color saturation of a video clip.

<Edge Detect> Render the video as a line drawing based on edges or,(colormx) render the video in a cartoon-like graphical format.

<Sharpen>  Sharpen the images in the video.

<Monochrome>  Convert the video to gray scale.

<Insert Text>  Place text on top of the video clip.

<Trim Clip>  Remove a section of a video clip. Select the section to be deleted in the same manner as extracting a clip shown above.

<Snapshot>  Take a snapshot of the video currently playing. The snapshot file name will appear in the entry boxes and the snapshot will be saved in the 'videos' directory.

<Negative>  Create a negative of the video clip.


Creating a Clip From an Image

You may create a video clip of arbitrary length from a still image of type JPG or PNG. In the <Create Clip From Image> box, select a duration in seconds (default 10). Select one or more images from the entry box(s). You may copy .jpg or .png images to the 'videos' directory or use snapshots created as shown above. Click <Generate Clip> to generate a clip(s) from images. You may subsequently add text to these as shown above.


Audio Options

<Strip Audio>  The audio track(s) from the selected video clip(s) will be removed. Note: video clips must have audio tracks if they are to be joined.

<Add Audio>  Add (replace) a pre-recorded audio track to a video clip. Select two files. the first (uppermost) must be a video clip and the second will be the audio track source (audio file or video clip). Click <Add Audio> and the audio from the second file will become the audio to the video clip. Any previous audio on the video clip is lost.

<Null Audio 44100>
<Null Audio 48000>  Add an audio track with the noted sampling rate to the selected video clips. The audio tracks added will be silent. This option is useful for adding audio tracks to videos so that the videos may be joined. Only videos with audio tracks may be joined.


Joining Clips

<Join Selected No Transition>  Will attempt to join select clips without regard to geometry or timing. Results may be weird if it works.


Transitions Joining

Joining clips with intervening transitions requires that the videos be or the same geometry and timing and that they have an audio channel. See <Standardize> for details on standardizing clip geometry and timing.

If the selected clips are compatible they will be joined into a single clip with the selected transition between each. The duration of the transition (default 2 seconds) may be selected with the spin button.

The <2x1> button with tile two clips side by side into a single, wider clip. Two videos must be selected and they should be of approximately the same length. Audio will be from the fist clip.

The <2x4> button will tile four clips, two to a row, into a large clip. Four videos must be selected. The videos should be of approximately equal length. Audio will be from the first clip. 


Standardize

The selected videos will be reformatted to the selected geometry and each will have the same timing. Standardized videos may be joined.

Renaming a Clip

Click on an entry box and a popup will ask for the new name of the clip.



Installation

The main Linux module is Zippy.c with additional code contained in the sgv-code/common directory. 

To compile and run in Linux:

1. Depending on the target Linux system, run the correct Install script.

		./DebInstall.script (for Debian based systems such as Mint and Ubuntu)
		./ArchInstall.script (for Arch based systems such as Manjaro)
		./FedInstall.script (for Fedora/Red Hat based systems)

These scripts MUST be run as root. They install standard system software that is needed for compilation.

2. Depending on your target system, run ./configure:

		./configure --with-system=debian (the default)
		./configure --with-system=arch
		./configure --with-system=fedora

3. Compile the system:

		make -B
	or
		make -j x -B

	where 'x' is the number of CPUs to use.

4. Check the default colors for gnome-terminal. In some systems the default results in unreadable text. Open gnome-terminal, select Edit | Preferences and set the Colors as desired. Gnome-terminal is installed if needed by the install scripts. Alternatively, you may try altering the desktop theme settings. 

5. Run the system:

		./Zippy-bin


The graphics code is based on GTK 3 (3.24 at this point in time).

This is an ongoing project and there will be changes, corrections and additions as time goes by.

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

Notes

To run, execute Zippy-bin from the compilation directory. 

Place videos or copies of videos you will be working with in the 'videos' sub-directory of the Zippy directory.

Any videos or still image snapshots created by the editor will be placed in the sub-drectory 'videos' and will be named with an appended ascending integer.  Output videos are in MP4 format and still images are in PNG format.


FILE NAMES

File names created by Zippy are mostly the same as the input files except an accession number is added at the end of the original file name. Higher numbers indicate later videos or images.

Video Operations

When you have clicked a button to initiate a video editing operation, please wait until the button you clicked returns to normal and the wait banner disappears.

DO NOT ATTEMPT ANY OTHER ACTIONS DURING VIDEO PROCESSING.

Video processing takes time. Randomly clicking other buttons will not increase the speed and will probably result in the video being trashed.

Video processing is done by ffmpeg commands that are constructed based on your selections. The ffmpeg commands are output to the originating console.


HOT KEYS

Home  - move to start of video file
End	 - move to end of video file
Left Arrow  - move back 2 seconds
Right Arrow  - move forward 2 seconds
Up arrow  - next frame
Space Bar  -toggle Pause
Escape  - reset player

CODECS

Most video codecs work but some, rarely, don't.

Some video drivers on Linux do not have the software libraries required by libvlc to decode video.  The xserver-xorg-video-nouveau driver does. If you experience problems, you might try reverting to an earlier hardware driver (for example, nvidia 390 works for me but nvidia 470 does not) or switch to xserver-xorg-video-nouveau. 

Ordinarily, the driver software issue, in the desktop VLC app, can be controlled by the --avcodec-hw=none parameter but the libvlc API forbids the developer to do this for reasons that are not adequately explained. If you have this problem, rendered video will not play in the editor but will play with other video players such as mpv or the VLC desktop with the aforementioned parameter.

Ubuntu appears to have dropped support some vdpau wrappers. There are Debian versions here:

http://ftp.debian.org/debian/pool/main/v/vdpau-video/

that may help (be certain to select the correct file). The one you want is probably the latest for your machine which is likely to be an amd64 architecture.

That said, you can safely ignore error messages of the form:

libva info: VA-API version 1.14.0
libva error: vaGetDriverNameByIndex() failed with unknown libva error, driver_name = (null)

These are harmless.

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

Windows WSL2

The code works with Windows 11 with WSL 2 / Ubuntu installed subject to availability of video libraries (depending on your video card and its support under Windows 11).

Some ffmpeg filters are unavailable in the WSL2 Ubuntu distro. This causes some options to fail. Hopefully, WSL2 will soon move to a more recent distribution.

Some window manager features are unavailable in WSL2 Ubuntu. Sound rendering can be choppy initially and the window manager can freeze under load. WSL2 is a work in progress.

The 8 second rule: You must wait until the subsystem running your Linux distribution completely stops running and restarts for configuration setting updates to appear. This typically takes about 8 seconds after closing ALL instances of the distribution shell.

If the WSL2 window manager hangs, close ALL instances of Linux and wait at least 8 seconds before restarting.

