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

July 7, 2026


Linux Media Editor

Copyright (C) 2018 - 2026 by Kevin C. O'Kane

Kevin C. O'Kane 
kc.okane@gmail.com
https://www.cs.uni.edu/~okane 
http://threadsafebooks.com/

------------------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
------------------------------------------------------------------------------

Acknowledgments

Run time routines from the VLC run time library are used for audio services.
No VLC source code is used.

ffmpeg commands are used in this project but ffmpeg API is not.

Zippy. Zippy is a puppy. His accomplice is Mabel. They are very good at
cutting things up. If you hit the right button in the right way, you will
see them waiting to shred your video, or socks, whatever.

Check out the latest video currently at:

    https://youtu.be/fZIfAb0x9io

NOTE: If you modify code in the *.in files, you MUST run configure.

Installation

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

At the moment, this compiles and runs on Windows 11 with WSL2. Inherent
timing issues with libvls and WSL periodically make audio playback contain
noise. To avoid this, the WSL version sends audio directly to ALSA and
bypasses PULSE. However, created files containg no audio errors. Changes
to libvlc and WSL periodically cause problems in this area. 

Note: this project only operates on Debian compatible distributions.
Installers for other distros are not currently maintained.

To compile and run in Linux (also WSL Ubuntu 24):

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

		sudo ./DebInstall.script (for Debian based systems such as Mint and Ubuntu)
		
	   This scrips MUST be run as root. It instalsl standard system software
	   that is needed for compilation.

	2. ./configure

	3. Compile the system:

		make -B -j 4

        Where "4" is the number of CPU processors available

    4.  Install:

        sudo dpkg --install sgr-zippy-amd64.deb

	4. Run the system:

		sgr-zippy


The graphics code is based on GTK 3.

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

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

Notes

The code is written in C and uses various C libraries and GTK3. The layout is
built by Clade but Glade is not actually part of the code. 

GTK4 has been released. GTK4 is not compatible with GTK3 applications. GTK4 has
little to offer and removes some features from previous versions. GTK4 is 
expected to be replaced by GTK5 which may itself be incompatible with GTK4. 
GTK3 remains under support and will for many years to come. 

Glade is used to create an XML layout file that maps application widget 
placement and properties.  The XML file, once built, no longer requires Glade. 
Glade is no longer under support but remains available and functional. 

Given the large investment in GTK3 applications, it is likely that there will 
be a fork of GTK3 in the near future. 

----

All video processing is done by ffmpeg command line commans with complex argements.
If a command fails, the error message from ffmpeg will be shown in the stdout
of the terminal originating theZippy Clipper. If Zippy Clipper is initiated
from a launcher, these messages are, at present lost. In the event of an error,
the Zippy Clipper will display in a message box the ffmpeg command that caused 
the error. You should look to the terminal for further details. 

If an ffmpeg command fails, you can usually re-run the command from a terminal
by cutting the command from the error message and pasting it into a terminal
window and hitting <enter>. This should rerun the command in standalone mode
and you will see all the outputy from the command.

Sadly, ffmpeg error messages can be opaque. A present development goal is
to verify arguments to ffmpeg in order to prevent errors. This is a work in
progress.

The most common errors involve joinging files that are of different timing
or geometry.

----

ffmpeg will attempt to use all CPUs available. This will increase the temperature
of your system considerably. You should monitor your system to ensure it does not
overheat. In most cases, there will be no problem but not all. There are Linus
apps that will allow you co tontrol maximum CPU clock speeds. A lower closc speed
reduces hear load. Example:

sudo -S /usr/bin/cpufreq-set -c 0 -u 2.9ghz -g OnDemand < /home/yourid/PW
sudo -S /usr/bin/cpufreq-set -c 1 -u 2.9ghz -g OnDemand < /home/yourid/PW
sudo -S /usr/bin/cpufreq-set -c 2 -u 2.9ghz -g OnDemand < /home/yourid/PW
sudo -S /usr/bin/cpufreq-set -c 3 -u 2.9ghz -g OnDemand < /home/kane/PWo

where PW is a file in your home directory conating your password (very bad
from a security point of view). Otherwise, crmove the code on each line 
beginning as the '<' sign and manually enter the password at prompts.

The specific frequencies (2.9ghz) will vary depending on your system. You may
need to install cpufrequtils which contains cpu-freq-set. The above is for
a system with four CPUs (0 thru 3). Your count may differ.

----

Building the installer involves ;pcating and adding system library references.
As Linux versions appear, older libraries are replaced by newer versions.
New versions usually have higher numbers such as:

libavformat57
libavformat58
libavformat59
libavformat60
libavformat61
libavformat62

(At this wrting, the last of the above is current). 

In the file sgr-zippy/sgr-zippy-amd64/DEBIAN/control you will finde these
references on the 'depends' line. If your version of Linus uses a  newer or
other version of the items on this line, edit this line to include them.
Note the OR (|) symbol between versions.

----

Zippy finds its files from a directory. By default, this is your home directory.
You mach swicth to another directory in the app. 

You may establish an alternative defailt directory by creating and exporting
an environmental variable named ZIPPY which contains your desired default 
directory:

ZIPPY=/home/myuserid/a-directory-of-videos
export ZIPPY

The above should be run in the same process (e.g., a terminal window) from which you
start sgr-zippy. `

Zippy will create three subdirectories in any directory in which it is active. These 
are named snapshots, stills and thumbnails. The first will contain snapshot images you 
may create from videos. The second contains stills captured serially from a video file. 
The third contains thumbnail images used in the app to identify files. 

If you have a file named aaa.mpg and Zippy created a thumbnail for it and, later,
you replace it with a differnt file with the same name, you should re-scan the 
directory to update the thumbnails.

----

Previews

Previews can take several seconds to activate. Be patient.

Previews appear in an independent ffplay window. The contents of this window
are the output of the ffmpeg command being previewed. The ffmpeg command is run 
as a separate process but it's output is re-directed to an ffplay window rather
than a file. The ffplay window displays images as they are received from ffmpeg.
This means that (1) there will be a lag time until the ffplay window appears due
to initial image buffering, and (2) the images in the ffplay window may be jerky
or contain pauses depending on how fast the ffmpeg command is running and the
speed of your machine. 

Previews will be displayed for about 15 seconds.

----

Next to each video icon is a checkbox. Checking the box selects the video.

Many of the features work on one or more selected videos or audios. For example,
if you want to convert several videos to a standard size and format, the Video
Adjust / Standardized button will convert all selected videos to the format selected.

Some operations only apply to the currently playing video

----

Only one operation at a time is permitted. So, if you want to convert 5 videos to
a standard format and THEN convert them to monochome, the operations must be
done separately.

----

Some operations only operate on one video or audio, usually the one which is 
playing. The Create Clip button, for example, creates a clip from the current 
video using the current start / end and crop settings. Only one video is created
at a time. 

----

The meters display the sound levels being received by the PulseAudio
PipeWire API. If you have muted or reduced the volume of PulseAudio, the graphs will be
reduced by a corresponding amount. The graphs accurately reflect video sound
levels only when PulseAudio playback is set to 100%.

----

You should only join videos of the same file type (.mp4, .mkv, etc.), geometry,
and timing characteristics. Joining or otherwise mixing video clips with different
file types, geometry or timing will usually fail.

The "Standardize" button can be used to convert one or more clips to a standard
format, geometry, and file type.

It can occur that even if your original video is of the default file type, extracted clips
from it may not be compatible with the original. This is because the extracted clips
may be of different geometry or use a default set of timing  prarmeters that may differ
from the original.

----

Zippy is compiled for a default file type, normally mp4. Files created by the
editor will be of this type and all files edited by the editor should be of this
type. Use the "Standardize" button to convert one or more files from another
format to the default format.

You may configure the editor for other default types by adding an option to 
the configure command giving the default type:

	configure --with-fmt=mkv && make -B

The above configures the editor to use MKV files as the default.

----

When you join two videos with a transition, the resulting video will be shorter in
time than the sum of the times of the constituent videos. This is because during the
transitions, both videos are briefly playing concurrently and thus overlapped.

----

If you modify the code, modify the *.in versions and be SURE to run configure
before you compile. The program configure converts the *.in files to *.c
files and it is the C files that are actually compiled. Any changes you make to
a .c file directly will be lost.

----

Cell Phone Videos: 

Cell phone videos have a rotation meta data parameter.

Rotation 0 is called 'left' and this a a wide screen format where the top of the
phone is in your left hand when recording.

Rotation 90 is called 'normal' and this is narrow screen format where the top of
the phone is up.

Rotation 180 is called 'right' and this is wide screen where the top of the
phone is in your right hand.

Rotation 270 is called 'upside down' and is narrow format with the top of the
phone down when recording.

Rotation 0 is fully supported. You may play and create clips with rotation 90
only. Cropping and other features are restricted in rotation 90.

The other rotations may be played but are mostly unsupported.

You may convert rotations 90, 180 and 270 to a supported format with the 
'Standardize' tile.

----

Video Operations

When you have clicked a button to initiate a video editing operation, please wait until
the operation has completed. 

DO NOT ATTEMPT ANY OTHER ACTIONS DURING VIDEO PROCESSING.

Video processing takes a lot of 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. Copies of the ffmpeg commands are output to the originating console.
There is a button to abort an on-going ffmpeg operation. If you do so, the
video clip being created will be trashed.

----

Hot Keys and Button Equivalent

Home             move to start of video clip (Go To Clip Start)
End              move to end of video clip  (Go To Clip End)
Left Arrow       move back 0.5 seconds (Back)
Right Arrow      move forward 0.5 seconds (Forward)
Down Arrow       decrease playback speed
Up Arrow         increase playback speed
Ctrl-Left Arrow  move back 2 seconds (Back)
Alt-Left Arrow   move back 3 seconds (Back)
Ctrl-Right Arrow move forward 2 seconds (Forward)
Alt-Right Arrow  move forward 3 seconds (Forward)
Space Bar        toggle Pause (Frame By Framwe Mode)
Escape           reset/restart player (Restart)
d                scroll page of media entries down (Page Down)
e                mark clip end (Mark End)
f                halt all ffmpeg actions (Halt ffmpeg)
h                halt player and release video (Halt Player)
p                play clip from start (Play From Clip Start)
S                mark clip start (Mark Start) Note upper case.
u                scroll page of media entries up (Page UP)
s                screencap the currently playing video

----

CODECS

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

Some video drivers on Linux do not have software 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 (nvidia 390 works for me but nvidia 470
does not) or switch to xserver-xorg-video-nouveau. 

Ordinarily, in the VLC app, this 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 VLC 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.

----

How-To Videos

The How-To videos are on a server (https://threadsafebooks.com) in order to reduce the size
of the distro. Internet access is required to view them. The videos will be updated and added
to as time goes by. The list of accessible videos is in the file program.lst in the
Zippy/howto directory.

In general, videos from the Internet can be edited if you have read acces and a URL that 
points to a file whose video format is compatible with the VLC librarty. This does not
mean you can edit a YouTube video with just a YouTube URL. YouTube URLS do not point
to files.

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

To limit cpu usage in Linux to keep from over heating. Numbers are cpu core nbrs.
The following command will only run on CPUs 0, 1, 2, and 3 (this assumes you have
more than 4 CPUs).

taskset -c 0,1,2,3 command


