avsFilmCutter

avsFilmCutter's User Guide

version 0.0.1.9 beta

A script development tool for AviSynth with built in video viewer / player and instant script output properties or error details.

A tool born from my laziness and inspired by the extraordinary software written by Nic, Hank315 and others whom hang out at Doom9's forum, you may post comments to the AviSynth usage forum "avsFilmCutter a new tool for AviSynth thread" or you can email your remarks directly to the following.


Contents

License and Terms of use.

Feature overview.
FilmCutter Options
Audio Processing

Encoding interface

Appendix

FilmCutter has three main tools.

Script Editor

Media / Video Viewer

Video Frame Editor

Other Useful Stuff

Tool tips.

FilmCutter's Options Dialog Window

This dialog window allows the user to changes some options.

Look at the "
Options help page."

Audio Processing
Encoding Interface
Appendix


Script Editor

The script editor used by FilmCutter is called "Scintilla" © 1998-2003 by Neil Hodgson, it provides many features found in the best text / script editing software such as Notepad++.

The file displayed in the edit window becomes the source script file for FilmCutter's viewer and scene editor.  You may load files into this editor from the scene editor view or even the media viewer.  You may drop script files into the window.  If you use the "open the file with" feature of Windows, FilmCutter will open the file into the script editor and switch to the editor view.

Menus:

All menus in FilmCutter are pop ups.  Right clicking when the mouse pointer is over the script edit window will display a menu for that window.  Right clicking over the border that surrounds the editor will display the main menu.  Right clicking the "Encode" button or a Tool button for example opens a dialog box for adjusting settings or setting up something.  You do not have to hunt thought the menus to change a setting always.  If there are adjustable options for a button, they are under your right mouse button finger.


F1 and Filter Funciton Parameter Help:

This document can be launched from within FilmCutter, select Help - Open User Guide in the main window menu.

AviSynth documentation is also available as noted above and if the user (that's you) highlights or selects a function name and then presses F1.  It sort of works, the problem is that the help.html file for, lets use "Mpeg2Source" as an example, a filter or plug-in function may not use the same name as the function or filter called in a script i.e. DGDecode.dll and Mpeg2Source.  This will be addressed in a future version with a redirect list customizable by you, the user.

Another example of this problem with directing you to the correct help page is "Animate / ApplyRange", ApplyRange is found in the html file for Animate(animate.htm).  In the interim FilmCutter will open a windows search window for the AviSynth documentation folder.  You can then paste the function name into the "find in file" box and click search.

Selecting the complete function name and argument list yields another option.  This one is explained in more detail below.


Filter / Function Look-up List and Function Parameter Dialog

If you select the whole funciton " trim(155, 156) " and press F1 FilmCutter will open the filter/function parameter dialog window and try to fill the parameter cells with the argument values.  This kind of works for some filters and funcitons and for others not so well.  Anyone out there really like writing parsing code, I could use some algorythm help.

Filter/Function lookup is available, sort of an autocomplete thing.  Goes something like this.

To view the filter/function list you have the following choices:

  • Press Ctrl+Tab.

    Repeatedly pressing Ctrl+Tab will open and close the filter/function drop down list.  When open you may use the arrow keys to look though the list for a function or filter.  Press enter to add to your script.  Press Tab to open the parameter help dialog window.

  • Click the down arrow next to the list window.

    When open scroll down with the wheel or scroll bar and just click or hold the mouse over the filter/function and press Tab to open the parameter help dialog window

Alternatively you can type the beginning letters of the filter/function name and watch the list highlight jump to the first match it finds.  Backspace works if you type an incorrect letter.  And the statusbar's far right column shows "Filter search = " as you type so you can see if you make an error.

When the filter you are looking for is showing you may do one of the following:

  • Press Enter:  The parameter dialog window will open.
  • Press Ctrl+Enter:  The filter/funciton will be added to your script without arguments(())

When the filter/function parameter dialog box is open you can tab through the data cells adding parameters as you wish.  You can right click on a cell and select insert filename or from the keyboard press Ctrl+Shift+O to open the filename dialog box.  The bottom window shows the parameter definition string that avisynth.dll provides.  The window above that shows the parameters you will be adding for the function.  Press enter to insert the function into the script or click Ok.

This little goodie will not keep you away from the AviSynth and plug-in documentation but it might make it a little easier.

This parameter lookup feature of AviSynth's is broken to some extent in all versions prior to 2.57.  See the appendix for more details.

Please note, all internal AviSynth filters and functions make it to the list which is created when FilmCutter is first opened.  However the plug-in functions in the list are only from those Dlls that reside in AviSynth's plug-in folder.  There is no provision in avsFilmCutter to list functions from Dlls that reside elsewhere on you computer, yet.


Tool buttons:

The editor has a six button toolbar that is programmable.  Right click to setup each button.  If you like an external video viewer use button six.  Button six is shared by the trim edit window.  Also when a script is launched with button six from the script edit toolbar the viewed script displayed in the window will be sent to the external viewer not the saved script.  Only button six the one on the bottom right will gather the script from the window without you having to saving the file.  Tool button setup is like encoder setup except no "%ofile.ext"(out-filename) in the command line for tools.  For tool buttons 1-5 when using programs like "AVSEdit", that edit and save the script when closed, FilmCutter will reload the file after the external tool has been closed.


Encoding:

You may encode your saved scripts directly from the script editor (more details here), press F7 or use the Encoding section of the script editor menu.


Script output properties:

At any time during the script writing process press F8 or select "Show Script Output Properties" from the script editor menu.  Some of the items displayed are shown below.  For scripts loaded into the editor FilmCutter will load the script file or a file(windat.avs) it creates from the text in the editor window, into AviSynth and collect the data or error information, which it then displays.  For media files loaded into the media viewer the files are run though a common interface that provides data for some but not all types of files.

FilmCutter will display, if it detects AviSynth is outputting error information, details about the error AviSynth is reporting.


Script Preview

If you want to view your script press F5 or alternately select Preview Script from the script editor menu, the internal video preview window will load up the unsaved text from the editor and display the first frame, display an error message or crash (see the appendix).  Alternately you may press F6 which will switch to the preview window and begin to play.  While working in the preview window F6 will play or stop the video.  Press F5 to return to the script editor or alternately select Script Edit Window from any menu.  If you choose to switch back to the script editor to make some changes and again switch to Preview, the frame number last displayed from the previous visit to preview will be displayed, but there is more.

FilmCutter's script preview has some options.

All preview modes show a track bar for scanning the video, a " jump to frame window " and a frame number display with little arrows which advance and reverse the frame count by one (the keyboard shortcuts should work as well).

Script menu -> Script Options -> PreView Options -> Info

If at any time the "Info" line in the menu is checked, FilmCutter will display a list of properties for the clip being viewed.  This data is collected directly from AviSynth and the color space data should be more correct when using RGB.  Field parity is also shown but will display ??? unless the user has defined the field order using either "AssumeTFF" or "AssumeBFF" in their script.

Script menu -> Script Options -> PreView Options -> w/Script Editor

Same script editor, same menu, just smaller showing only a few lines which will increase and decrease as the window size is increased or decreased.  You get another button " update " or press F4 which updates the video window with your changes to the script.

Once again these modes can be set by using either "Script Options" -> "Preview Options" in the script editor menu or on the fly during the preview session using the video window's menu "Preview Mode".  A third option is the preview window frame menu contains Info, No Script Editor and w/Script Editor

Note that when using the script editor in preview an Update F4 button is shown which allows the user to update the video window after changes have been made to the scirpt.  Update does not save the script.


External Preview

Again, the bottom tool button (number six) will launch the window text just as the internal viewer does.


Options

In addition to some of the options listed elsewhere in this guide the script editor memu has script options that change the Font used by FilmCutter's script editor and some AviSynth options to play with.

AviSynth Options


Audio Processing

If your encoding solution includes a trip through the internals of a version of VirtualDub to save out the audio portion of your script as a wave file, stop, FilmCutter will save that wave.  It will save lots of waves.

What ever audio format your AviSynth script is using, select 'Save Audio as Wave" from the main or script editor menus to open the save wave dialog window which should show you some details concerning the wave file that would result from you clicking on the save button.  Input and output files are shown and the output filename can be changed.  Also you will find a check box at the top left, "Save each channel a wave file", which when checked will cause FilmCutter to break the channels out as individuals and then save them as individuals, the naming convention is shown below.  Also the maximum file size for a correctly formatted wave file is 4 GB, if your resulting multi-channel file will exceed 4 GB FilmCutter will automatically switch to the individual file mode.  When using this feature the files will have the channel ordering that AviSynth uses.

Channel Number Description Out-file Name
1front left channelYourFile_FL.wav
2front right channelYourFile_FR.wav
3front center channelYourFile_C.wav
4LFE (Subwoofer)YourFile_LFE.wav
5rear left channelYourFile_SL.wav
6rear right channelYourFile_SR.wav
7not yet 
8not yet 

Encoding interface

You have created your script adding filters and have tweaked them to your pleasure, cut out the junk or the commercials, now it is time to encode your work.  FilmCutter has an interface for launching your scripts into another application with the emphasis being encoding.

A very simple example would be starting VirtualDub with a single click of the mouse or starting VirtualDub with your script loaded (no need to leave FilmCutter).  A very complex example would be setting up a encoding configuration where FilmCutter would launch an audio encoder then a video encoder and when finished multiplex the audio and video together while you sleep, work or watch.  FilmCutter does not multiplex yet but does the other things pretty well.

Applications like VirtualDub encode using a codex (compressor/decompressor) installed on your computer.  FilmCutter needs the application to connect to these codexs.  Encoding applications like QuEnc and HC are devoted to encoding in one or a small number of formats related to a given task, both are setup to use AviSynth scripts as the source.

To setup encoding from FilmCutter see the included help file, Encoder dialog help.


Additional information about using the script editor can be found on the web site or go directly to fcwebguide1.html


Video Editor / Video Scene Editor

Here is the meat and potatoes of the program, the reason I started this project.

I wanted a simpler way of collecting the frame numbers needed to use the trim function in AviSynth.  Load your source script, navigate though your video click the FilmCutter icon button and you will soon have a list of frame numbers.  It may not be just that easy, but it is close to that easy.

In simple terms.

Step by step.
  1. Open your source script then save the project or follow down and save later.
  2. Select your first frame of your first scene, then click FilmCutter's icon.
  3. Select last frame of this scene and click FilmCutter's icon.
  4. The "Add" button is now enabled and you may click it or select a transition from the drop down box.
  5. Add the scene to the project.
  6. Save the project.(you must have a project file open to view your scene selections and their transitions)
  7. Once the project is saved the Source and Project radio buttons will enable.  Click the Project radio button and you may view the scene you've added to the list.(all editing features are disabled when the Project radio button in selected)
  8. Click the Source radio button to continue, add another scene or edit the existing one.
  9. Save the project again.
  10. Click the Project radio button to switch to project and view the video, encode or switch program views to see the output script in the "Script Editor Window".

Output script or project script generation is somewhat automatic, the file is written with the naming conventions shown below.  To make sure the file is written you must only switch from the source to the project mode in the editor.  Each time you switch to project the file is written.

Project file:

" weddingvideo.jfc "

Project output script:

" weddingvideo_fcprj.avs "

Row Numbers Buttons

The scene list window has buttons on the left side that represent the rows of the list, click the row number to edit a row.  If you other click the row buttons a short menu list appears (insert row, delete).

TabControl

When the user has a project open in FilmCutter the script editor switches to a tab view.  The tabs at the top allow the user to switch between the source and project scripts.  The rest of the program tracks the change just as if you had clicked the source/project check box in the video editor window.

Warning!

If you wish to edit the project script from the script editor window please save it under a different file name as FilmCutter will write over it the first time it is called to be used.

You can find a more details about the video editor on the web site at
fcwebguide2.html

Media Viewer / Video Player

This is just the video window (aspect ratio corrected) without the other buttons and windows.  FilmCutter contains a not so complete implementation of DirectShow.

The DirectX viewer works very well with AviSynth scripts and mpeg1+2 ac3, wmv, wma, and wav files as well.  The focus when using this player is to view and play an avs script for AviSynth, other media types will play depending on your system and the installed decoders.

Of note is the following example.

The system that avsFilmCutter is being developed on today is a Pentium 4 Media Center machine made by HP, its nice.  Microsoft as I remember it, no longer provides an Mpeg 2 decoder with Windows, even their Media Center versions.  This machine came with a copy of InterVideo's WinDVD.  I do not know if this combination of Media Center and WinDVD is common but Media Center will not play dvds if you remove WinDVD.  Attempts to install a decoder, for example the famous "Ligos" decoder were unsuccessful, my point follows.

With the ligos decoder installed the seek functions in FilmCutter work well as long as you don't seek the next frame, the direct show functions fail, crashing the program, the WinDVD decoder behaves differently locking up just the player, but only after seeking wildly beyond a few frames.

Your results will differ I am sure, nevertheless the direct show viewer/player is here to stay and will work much better as I tune the interface.

Tip: Leave the filters out of your script or better comment them out until you have your trim statements done then save the project remove the number signs and encode away.



Appendix

Keyboard Shortcuts

Script editor view:

Script Preview:

Video Navigation and Control Shortcuts

  • Spacebar
  • Play / Stop
  • Right Arrow
  • Forward one frame
  • Left Arrow
  • Reverse one frame
  • Alt+Right Arrow
  • Forward framerate * two
  • Alt+Left Arrow
  • Reverse framerate * two
  • PageUp
  • Reverse framerate * ten
  • PageDown
  • Forward framerate * ten
  • Alt+PageUp
  • Reverse framerate * one hundred
  • Alt+PageDown
  • Forward framerate * one hundred


    AviSynth Error Reporting

    Some of you know that when you make a syntax error in a script, AviSynth can and mostly does display an error message in the video window.  That information is available to FilmCutter directly and will be displayed in dialog or message windows.  Some errors not related to your script can cause FilmCutter to receive error information when loading function names at program start.

    If the error is system related (caused by other that your script errors), avsFilmCutter tries to provide some info about the nature and persistence of the error.  The following list of error codes are provided by FilmCutter.

    Error codes

    1. AVSERR_01: avsFilmCutter can not find "avisynth.dll".  AviSynth must be installed on your computer or many features of avsFilmCutter will not be available.
    2. AVSERR_02: AviSynth could not return the required process address.  AviSynth interface is not available.
    3. AVSERR_03: Could not open an interface type that I liked.  This is an AviSynth version issue, use version 2.52 and above, 2.57 and later is best.
    4. AVSERR_04: AviSynth reports a fatal error.  avsFilmCutter will not be able to interface directly with AviSynth.
    5. AVSERR_05: avsFilmCutter can not get an environment pointer from AviSynth.  This is not a user script problem.  It is either a corupt installation of a dll or avsi error in the plugin folder.
    6. AVSERR_06: avsFilmCutter could not determine what version of AviSynth is installed.  Your installation may be functional but its older than 2.07.
    7. AVSERR_07: AviSynth reports an error when asked for Internal function names and keywords.  Possible version conflict.
    8. AVSERR_08: Internal function names and keywords can not be looked up using versions of AviSynth earlier than 2.52.  Or there is an error.
    9. AVSERR_09: AviSynth reports an error when asked for Plugin function names and keywords.  Possible version conflict.
    10. AVSERR_10: Plugin function names and keywords can not be looked up using versions of AviSynth earlier than 2.52.  Or there is an error.
    11. AVSERR_11: AviSynth reports an error in your script.
    12. AVSERR_12: avsFilmCutter has detected an error when trying to open your script.

    Some notes about filter / function parameter help and AviSynth versions.

    Starting with version 2.55 of AviSynth, avisynth.dll reports both the plug-ins function name and it's alternate name.  In other words functions such as Mpeg2Source will have more than one name.  In the filter / function list you will find both Mpeg2Source and DGDecode_Mpeg2Source listed.  This means that all externals / plug-in function names are listed twice, this issue is on the list and is not that difficult to deal with except that it gives me a headache and from a cold start gathering the filter names makes FilmCutter seem slow to start now.

    avsFilmCutter supports all versions of AviSynth that provide this filter / function information starting with 2.52.

    • 2.52 plug-in filter function names no parameter support.
    • 2.53 plug-in filter function names no parameter support or broken.
    • 2.54 plug-in filter function names no parameter support or broken.
    • 2.55 internal and plug-in function name lookup working can read internal function parameters, plug-in function parameters broken, alternate names for externals added also.
    • 2.56 internal and plug-in function name lookup working can read internal function parameters, plug-in function parameters broken, alternate names for externals working also.
    • 2.57 all working in Alexander Balakhnin aka Fizick's build, hope it makes it to release.
    • 2.57 all working.

    As I write this the powers that be are hard at work finishing version 2.58 of AviSynth, the latest information can be found here

    I have removed the specal build of AviSynth 2.56 built by Fizick as 2.57 from the web site because of the release of 2.57.  Anyone needing this build can email me I will help you get it.


    A Note about Crashing

    I believe that FilmCutter is stable but it is under heavy development.  Mistakes do get made, and generally they get fixed quickly.  An issues and bug list is here.  There is a but.  It appears that if AviSynth crashes so goes FilmCutter though not so much these days.  I have on occasion created a script that closes or crashes programs like Media Player Classic.  So I have setup FilmCutter to not load scripts into the video viewer under all circumstances, this prevents a really bad script from preventing trouble shooting.

    The following should explain.

    So if she is crashing, check the script with another program. If FilmCutter continues to crash when other programs don't, please send me the script.

    questions@avsfilmcutter.com


    The following lists show how the files that FilmCutter creates should appear.

    A project script file will be saved as "[your project filename]_fcprj.avs" in the project directory.

    ## Project Script Created by FilmCutter ##

    Import("E:\P_BellyDance\AirShowDance_FC.avs")


    t1  =  trim(46471,52985)
    t2  =  trim(23332,29611)

    t1+t2

    filmcutter.ini

    #### filmcutter.ini ####
    ########################


    avisynth path
    C:\Program Files\AviSynth 2.5\Docs\english\ (your path if different)

    project path
    (blank)

    last font
    Terminal (font name)
    -12 0 0 0 400 0 0 0 ff 1 2 1 31 Terminal (font data)

    last view
    3 2 0 1 9 1 (six digits "lastview" "preview" "information" "syntax" "tooltip levels" "line numbers")

    last ar
    1

    jump
    300 (scene / video editor jump button frame count you may ajust here)

    main window
    1 148 65 728 488 (placeholder, HorzPosition, VertPosition, HSize, VSize)

    write script
    1  0 (SpliceType 1 or 2, edChoice Not used )

    viewer Tech   static in 0.0.1.8b
    2 5 8   (three digits, ScriptPreview 0-2, MediaViewer 3-5, Scene/VideoEditor 6-8)

    button 1
    C:\Program Files\VDubMOD\VirtualDubMod.exe
    %filename
    button 2


    button 3


    button 4


    button 5


    button 6


    end filmcutter.ini

    encoder.ini

    #### encoder.ini ####
    #####################


    default encoder
    02


    encoder
    01
    path
    C:\Program Files\HC_15\HCbatch_015.exe
    file
    HCbatch_015.exe 1
    command line
    -i %filename -o %ofilename


    encoder
    02
    path
    C:\Program Files\QuEnc59b2\QuEnc59b2.exe
    file
    QuEnc59b2.exe 1
    command line
    -i %filename -o %ofilename


    end encoder.ini

    avsFilmCutter  ©   2005 - 2007 Robert Clark.
    www.avsFilmCutter.com

    AviSynth  ©   2002 - 2007 Ben Rudiak-Gould et al.
    www.avisynth.org

    Scintilla  ©   1998-2003 by Neil Hodgson
    scintilla.org