1. Linux Video Editor (lve) - features
--------------------------------------

- frame and GOP accurate editing of MPEG1/2 video files. differnt mpeg
  formats are supported: 

  o program streams ("PS") including DVD conform vob format, 
  o single elemtary video streams ("ES").
  o multiplexed, packed elementary A/V streams ("PES"), often used by 
    DVB recording software.
  o transport streams ("TS") - one video pid, but multiple audio pids.
    it's a further DVB format 
    (restriction: no error detection/correction, program tables won't 
     be analyzed).
  o PVA streams (experimental), used by some DVB recording M$-soft.
     
  the cutting engine is based on a self coded frame-server (demuxer)
  who's working on a special frame-index, which guaranties exact seeking
  to every frame. The "libmpeg2" of "mpeg2dec-0.3.1"-package is used 
  to decode video data. audio data will be decoded with help of "ffmpeg-0.4.8".
  Furthermore lve can use external audio files in "WAV"-format.

- lve can do hard cuts only, effecting transitions are not planned ! 
   
- The lve-GUI including audio output is based on "libSDL" (www.libsdl.org)
  The main window is divided in 3 parts:
  o left side, top half (in grey) you can find the "media-list", to 
    hold scenes of your media files.
  o buttom half (in green) you can find the "edit-list" to arrange and trim
    selected scenes coming from edit-list (per dragn drop).
  o right side, top half is the video displayer and navigation-unit to seek 
    and play your video. There are two modes - "navigation on scene" (default)
    and "navigation on full list". In first mode the navigation is based of 
    left and right limits of the selected scene. Second mode navigates in all
    scenes.
  o left mouse-click on a scene sets the focus to it and video is seeked to
    the first scene too. So you can also change fast and easy from media-list 
    to edit-list and vice versa.
   
- lve can load up to 128 different media-files with mixed formats like MPEG2,
  MPEG1 or different frame sizes (720x576, 352x288, ...) all together. 
  But the mainly intention of lve is to work with a few larger media-files
  (exp. "vobs"), divide them into single scenes (in media-list) and build the 
  final video (in edit-list) from desired scenes. 
  In edit-list every scene can be trimmed frame or GOP exact on its left 
  and/or right side. All actions will run very fast, because of using a own 
  GUI toolkit (based on SDL). 

- The scenes are displayed as thumbnails. To move a scene from media-list to 
  edit-list, it must be selected by left mouse-click (holding down the mouse 
  button) and move mouse pointer to a field from edit-list to release mouse
  button and drops the scene to the selected field or insert it before, if 
  field contains already a scene (there is no drag and drop animation, but
  cursor feedback).

- A realtime preview of the collected video in edit-list can be done at every 
  time.

- On a running preview, scenes wich contains the displayed video will be selected
  automatically ("yellow cursor" will follow the video).  
  
- The scene collection of the media-list can be saved as a media-list file 
  and can be reloaded on a other session. same is possible for edit-list as
  edit-list files (projects). 
  Such a edit-list can be used as input for a import-module of the "transcode"-
  program to encode the final-video. Writing a import-filter is in progress.
  
- some further tools allows to build the final video from source material
  without reencoding (and using the edit-list). if working with GOP accurate
  cuts the result wont have any dissortions on cut points, whereas with
  frame accurate cutted scenes there may be artefacts during the transition.
  there are different output formats supported:
  o separate files for video and audio, how audio data can be saved as
    copy of source, reencoded to MPEG1 LII or as plain "wav" file. 
  o multiplexed PS stream, DVD conform, usable as input for dvdauthoring
    directly, how audio data can be a original copy or reencoded to MPEG1 LII
    format.
 
- DVD Authoring of processed videos will be explained in "DVD-Authoring.txt"

- The actual status will be autosaved in backround, if lve is idle for more
  than 3 seconds. So after a restart of lve you can continue with your work in
  just a few seconds. 

- sources are available for free (GPL license), but you should have some 
  expierences with linux (and developing) to get lve to work.


1.1 lve - requirements
----------------------

- >= 500 MHz CPU with min. 128MB RAM, decoding with audio needs more speed !!!
  recommended up to 1 GHz CPU

- XFRee86 4.x with xv-support running with color depth >= 16-Bit !!!

- >= libSDL-1.2.x from www.libsdl.org (available in most newer linux 
  distributions)

- newer libqt-Stuff (>= 2.04) (see your linux distribution)

- the source-package must be extracted in "/usr/local", because lve has hard 
  coded directory names (at the moment ?).

- ffmpeg-0.4.8 -> use the package available from lve download place 
  IMPORTANT: please unpack the ffmpeg-package in "/usr/local/" too !!!
  Check if ./lve/ffmpeg links to your ffmpeg-directory (default is: 
  "./lve/ffmpeg -> /usr/local/ffmpeg-0.4.8" )
  NOTE: some older lve packages may need the older ffmpeg-0.4.7


1.2 Installing lve
------------------

all of the above described features are implemented, but there is no configure-script
available to setup the compile-environment for the destination-system.

Therfore some steps have to be done manually to get the package running:

- make sure to have libSDL (including develop-package) installed.

- extract lve-package (lve-jjmmdd.tar.bz2) in /usr/local and cd /usr/local/lve

- install ffmpeg-package like described above in section "1.1 Requirements" 

- type "make" to get the build

- test to start program by typing "bin/lve". please start lve from a terminal 
  window to see important messages (lve can't show messages on GUI !).


1.3 Using lve
-------------

- loading a media file is done by clicking on the button with "camera" icon. 
  This should start a external file-selection program (/usr/local/lve/bin/qdir).

  If you could not "qdir" to work, you can build a program or script, which
  prints the desired filename to stdout. If you place this as "qdir" in 
  /usr/local/lve/bin, you may load a media file (remember, with click on the 
  button with camera icon :-)
  "qdir" will be used also to load and save media- and edit-lists.

- while loading a media-file first time, there will be build the index 
  (may need some minutes) -> look at terminal window to see frames counting. 
  The index-file will be created in the same directory as the media-file with 
  the same name ".idx" appended.

- if you want to use external wav-audio, you shoud extract the audio from the 
  media-file in wav-format (exp. using transcode) and place the wav-file into 
  media-file's directory with the same name but with extension ".wav" instead. 
  ATTENTION: all your media file should have a extension of exactly 3 chars
  with "." as delimiter (.vob, .mpg, .m2v ...) 

  Example:
  
    test.vob (media-file) -> test.vob.idx (index-file), -> test.wav (optinal audio-file)
   
- to rebuild an index-file you can use /usr/local/lve/new/lvemkidx -i <media-file>

- In addition to the mouse there are much keys to control lve. some functions will be
  available by keyboard only. Here a list of the most control keys:
   q           = quit program
   p           = start/stop play
   PgUp/PgDown = jump forward/back in video, together with shift-key => short jumps
                 together with ctrl-key => long jumps.
   Up/Down     = single frame forward/back
   Tab         = cut scene on actual position (only in media-list)
   Backspace   = pack selected scenes together (only in media-list)
   0...9       = select correspondend audio track (if available)
   i           = print infos about the actual selected scene in preview
                 window (video should be stopped to see it)
   CTRL-ALT-r  = force a cleanup of lve's worksheet ready to start a new
                 task (media- and edit-list will be cleaned).

  key autorepeat will work too (exp. for single frame stepping).

- Here a list of mouse controls (please look screenshot to get a impression):

   Drag and Drop
    scenes of media-list are only draggable and edit-list is the only valid
    drop destination.
    
    scenes of edit-list are draggable and also dropable, which means you 
    can copy (hold left mouse button) or move (hold right mouse button)
    selected scenes inside the edit-list. 
    
    Drops behind the last scene will append the selected source-scenes. 
    Drops on any scene will insert selected source-scenes before this.

    On Dragging cursor will be changed to a cross.
   
   
   Buttons of the top line in main window (project bar)
    "Project-Open"-Button = load or new edit-list file
    "Project-Save"-Button = save (as) edit-list file
    "Project-Copy"-Button = copy edit-list file 
  
   
   Buttons of the line labeld with Media (media-bar) 
    "Camera"-Button     = load media file (first thing to do !)
  
    "Media-Open"-Button = load or new media-list file
    "Media-Save"-Button = save (as) media-list file
    "Media-Copy"-Button = copy media-list file 
  
   
   Buttons under video preview on navigation bar
    "|<"-Button = jump to start frame of first scene in "full-mode" 
		  jump to 1st. scene of the actual scene in "scene-mode"
    "<<"-Button = jump a block of frames back, where step wide is
                  (1/2/4) GOPs for (not/shift/ctrl) modified.
    ">" -Button = toggle to play/stop 
    ">>"-Button = jump a block of frames forward, where step wide is
                  (1/2/4) GOPs for (not/shift/ctrl) modified.
    ">|"-Button = jump to last frame of last scene in "full-mode"
		  jump to last frame of the actual scene in "scene-mode"
    "^"-Button  = jump 1 frame forward (2 frames while holding shift-key
                  and 5 frames together with ctrl-key)
    "v"         = jump 1 frame back (2 frames while holding shift-key
                  and 5 frames together with ctrl-key)

    NOTE: all "<<" / ">>" jumps are GOP accurate.


   Buttons in the middle line (edit-list bar)
    ">| |<"-Button = switch navigation mode between scene- and full-mode
                     (range selection for navigation pad)
    "Multi"-Button = select multiplier (range 1x to 3x) for navigation 
                     buttons "<<"/">>") in ctrl-key modified mode.
                     -> allows additional stepwides 8 and 12 GOPs.
    "< [ +0] >"    = audi syncing control to shift audio track around
                     relative to video track (unit is frames) 
 
    ... the next couple of buttons acts only on edit-list
    "->|"-Button = trim scene left: 
                   cut all frames left from actual postion displayed  
                   in preview window
    left "+"     = spread (grow) scene start aligned to previous GOP  
    		   (1 GOP each click)
    left "-"     = shrink scene start aligned to next GOP 
                   (1 GOP each click)

    "|<-"-Button = trim scene right: 
                   cut all frames right behind actual position displayed
                   in preview window  
    right "+"    = spread (grow) scene end aligned to next GOP 
                   (1 GOP each click)
    right "-"    = shrink scene end aligned to previous GOP 
                   (1 GOP each click)

    "scisors"-Button = remove selected scenes (only in edit-list)
    "copy"   -Button = not used
    "paste"  -Button = insert previosley removed scenes (only in edit-list)
  
   Left Mouse clicks on a scene
    o selects scene (focus) and seek to start frame of this scene,
    o in addtition holding shift-key will select a scene range,       
    o in addtition holding ctrl-key will select more scenes
    -> drag'n drop will work with multi selected scenes too :-)
    
   if all fields in edit-list are filled you can append a scene by drag it 
   over any field of the edit-list, than pressing shift-key and drop it 
   (release mouse button). At now you will be able to select next page of
   edit-list.

1.3.1 Restrictions of lve
-------------------------

- audio data of souce media files must have one of the following formats:
  
   o Separate WAV file or encoded MPEG1 Layer II stream with 
      32, 44.1, 48 KHz, 16 Bit, stereo.
  
   o AC3 stream (LPCM, DTS not supported). 

- for proper audio output, your linux kernel have to provide the "oss"-
  sound interface (you can use the core oss or the alsa variant with its
  oss emulation)

- ...
  

1.4 transcoding edit-list to final video
----------------------------------------

the archive "/usr/local/lve/src/import.tar" contains sources for an
import module useable  with the transcode-tool 
(availability see section "2. Resources" below)

since transcode releases of 2003, there is a directory
transcode.../import/lve, where "import.tar" has to be unpacked.
At this time there are needed some manual adjustments to get
the import module (import_lve.so) compiled/installed:

- the import.tar package contains a replacement for Makefile.in, which
  should lead to a proper makefile after configure transcode

- to build and install transcode with lve-import included do the following:

  1) cd transcode-x.x.x/import/lve
  2) tar xvf /path/to/lve/src/import.tar
  3) cd ../..; ./configure <configure-options>...
  4) cd import/lve; make
  5) cd ../..; make install
  6) cd import/lve; make install

  At now "edit-list" files can be processed with lve-import module
  (means transcoder parameter "-x lve").

- Also important transcode parameters which must be used for the lve-import 
  module are: "-V" and "-u 1,1" !


1.5 extracting scenes from source media without (VIDEO-) reencoding 
-------------------------------------------------------------------

lvedump is a tool to extract scene data from source media and dumps it
to the destination file without(!) reencoding VIDEO data.

NOTE: cutpoints will adjusted on GOP boundaries, because frame accurate 
cuts would need some reencoding around the cutpoints.
this means: on scene change lvedump additional includes all frames
beginning at the previous GOP relative to the real scene start will be
included. 
lve is designed to seek also GOP accurate with "<<"/">>"-buttons. if
you seek in this way immediatley before cutting, you will get WYSIWYG.

Scene ends rests always frame accurate !

Optionally lvedump can write a new "edit-list" corresponding to the 
created destination file. This helps to shrink rapiditly raw source 
material to needed scenes only without loosing quality. 
The resulting file(s) can be used later together with the new 
"edit-list" to create a frame accurate video by transcoding 
(using "import_lve"-Modul).
 
Audio will be written as separate (decoded) WAV-file or as reencoded
file in MPEG1 layer II format.

NEW: 
Also a further mode (beta state) is available to write destination
on the fly as muxed stream. the muxed mpeg will be accurate to use with 
DVD authoring ! -> it contains prepared VOBU packs and proper 
SCR/PTS timings to hold A/V in sync.
    
ATTENTION: there so no more need to patch ffmpeg, because package contains
its own (new) multiplexer code now.

NEW: 
while producing separate video streams it's possible to shrink
down the resulting video by requantization in the "compressed domain"
this can reduce size up 1/2 of orignal filesize holding good quality. 
this will work with MPEG2 video only .

1.5.1 Using lvedump
-------------------

lvedump [options] -i <edit-list> -av <video/audio-output> [-a <audio-output>]

-i	 use <edit-list>-file created with lve as input

-av	 output will be written to file named <video/audio-output>
	 if parameter "-a" is not used and source has audio, this
         name will be used for both video-output  with extension ".m2v" 
         appended audio-output with extension ".wav" or ".mpa" appended,
         if source has no audio there will be only video-output. 

-a 	 optionally to give audio-output file individual name -> in this
         case the video-output file will be named as specified by "-av"
         without any extension appended.
         if no source has no audio, this paramter will be ignored.

Options:

-e	  if source has audio, it will be reencoded to MPEG1 layer II, 
          with 224 kbs bitrate (16 Bit, stereo) and written to
          separate audio file named as with "-av" or "-a" parameter 
          specified.
        
-m	  this option should only be used alternativly to the "-e" option.
          audio will be reencoded like described above but the audio-output
          will be muxed on the fly together with the video-output.
          There will be only one output-file with name specified
          by the "-av" parameter (extension ".mpg" appended).
          also don't use the "-r <sf>" together with this option.
         
-l <el>	  produces additional a "edit-list" file with name <el>, which can 
          be read by lve (or transcode's import_lve-module) to get frame 
          accurate scene starts. It's the same like the input edit-list, 
          but adjusted for the output data.

-s <sr>   audio resampling, where <sr> is the sample-rate of the destination
          allowed values 48000, 44100, 32000 

-r <sf>	  shrinking down video size by factor <sf>, where <sf> is a float
	  beetween 1.0 and 99.0. but at the moment greater values than 2.0
          will have no reasonable effect (means stronger shrinking).
	  use this option only while producing separate video (ES) stream.

-p        video and audio output will forced to PAL norm (= 25 fps). 
          For the video stream, this  will be done very easy by adjusting the 
          frame rate code and GOP timecodes to PAL directly in chunk data  
          The audio portion will be adjuted in length but not in pitch.

-sh [<p>] shift audio by <p> video frames, how positiv <p>-values will delay 
          audio and negative <p>-values vice versa. if <p> is omitted the
          shift will be "-10" by default. 

NOTE: to redirect multiplexed output (option "-m","-M") to stdout, a simple
      "-" char can specified as A/V output filename ("-av -").

      if none of the both options "-e" or "-m" is used, audio (if available)   
      will be written as decoded WAV-file. 


Examples:

  "lvedump -i my-edit-list -av test" produces:
   - test.m2v with video data
   - test.wav with audio data

  "lvedump -e -i my-edit-list -av test" produces:
   - test.m2v with video data
   - test.mpa with reencoded audio data

  "lvedump -m -i my-edit-list -av test.mpg" produces:
   - test.mpg with muxed (reencoded)audio/video data

  "lvedump -e -i my-edit-list" -av video.m1v -a audio.mpa" will produce:
   - video.m1v with video data
   - audio.mpa with reencoded audio data

  "lvedump -l dst-edit-list -e -i src-edit-list -av test" produces:
   - test.m2v with video data
   - dst-edit-list with scene description adjusted to output file(s)

  "lvedump -r 2.0 -e -i my-edit-list -av test" produces:
   - test.m2v with up to 50% shrinked video stream
   - test.mpa with areencoded audio data

  "lvedump -M -i my-edit-list av - | <any command reading from stdin>" 
   - will pipe the multiplexed vob data to any other command capable to
     read from stdin, e.g. an application to stream vob data over network.  
  
1.6 index files 
---------------

lve and lvedump are based on a frame server engine capable to seek to the
desired video frame and extract the correspondend data exactly from the 
media file. therfore the engine needs to create an index file first.
this will be done normaly while loading the media file into lve.

in addition there is the standalone tool "lvemkidx" to (re)create index 
files. for example to build indexes for all desired media files (per batch) 
before loading them with lve ...

lvemkidx can check for a poper index file also, how it recreates the index 
only, if needed or it can build additional an "lve project file", which is 
loadable as edit-list or much better can be used as input for lvedump/lvemkdvd
directly without the need to process the media file with "lve" first.   


1.6.1 Using of lvemkidx 
-----------------------

lvemkidx [-p] [-l <prj-file>] -i <media-file>

-i      use <media-file> as input to create an correspondend index file.
        valid types for media files are: ES/PS/PES/TS/PVA mpeg streams
        (and lve project files itself, but without index creation). 

-p      to switch off forced mode, means index will be created only, if
        needed (probe-only).

-l      additional build the simple lve project file "<prj-file>" 
        loadable as edit-list or usable as lvedump/lvemkdvd input 
        file


2. Resources
------------

Homepage:
  
  http://home.arcor.de/gmo18t/lve/

Screenshots on:
  
  http://home.arcor.de/gmo18t/lve/


Source packages on:
    
  http://home.arcor.de/gmo18t/lve/download

libmpeg2- and liba52- packages on:
  
  http://libmpeg2.sourceforge.net

ffmpeg package on:
  
  http://ffmpeg.sourceforge.net/

transcode (linux video stream processing tool) on:

  http://zebra.fh-weingarten.de/~transcode/
  http://www.theorie.physik.uni-goettingen.de/~ostreich/transcode/
  
libsdl-package on:
  
  http://www.libsdl.org

3. Copyrights

all lve tools are 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, or (at your option)
any later version.

lve 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 GNU Make; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 
