From Avisynth wiki
Jump to: navigation, search
Author StainlessS
Version v1.13
Category Frame Replacement / Range Processing
License GPLv2
Discussion Doom9 Forum


[edit] Description

Prune is a simple plugin to trim() multiple source clips and splice the results into a new clip. Supports up to 256 source clips, with unlimited number of trims/splices into output clip. Prune can fade Audio (to reduce clicks between splices) for supported audio formats. The plugin will do AlignedSplice only.

v1.10, Implements 'Nickname's, Pseudonyms for the source clips, ie instead of '17 1000,2000' you could use eg 'Holidays_Aug_2011 1000,2000', to splice frames 1000 to 2000 of the clip 17 into the output clip. Supports Nicknames of up to 31 characters in length so you could use eg 'UncleBobsBirthdayBash 10000,14560', or 'Fred_And_Bobs_Wedding_Part_1 3485,6023'.

[edit] Requirements

*** vcredist_x86.exe is required for Prune-x86
*** vcredist_x64.exe is required for Prune-x64

[edit] Syntax and Parameters

Prune(Clip R0, clip R1, ... , clip R255, string 'Cmd',string 'SCmd', bool 'Show', bool 'Ver',int 'dv', bool 'NoErr',
    float 'Fade', bool 'FadeIn', bool 'FadeSplice', bool 'FadeOut', String 'Nickname')

Compulsory args:

        Rx,     Clip, No Default
                Source clips, at least one required. The first clip R0, up to R255 are supported, 256 clips in all.

Optional args:

        Cmd,    string, Default= "", Not set.
                Command file, use eg "PruneCmd.txt" for command file in your *.avs script directory.

        SCmd,   string, Default= "", Not set.
                Command String, as for command file, but commands supplied in a string rather than a file.

        Show    bool, Default= false.
                true = Show info.

        ver     bool, Default=false.
                true = Show version.

        dv      int, Default 0, possible values, 0 - 4 (Out of range values will default to 4==Debug==FULL)
                Generates info/warning/error messages during the filter setup stage (before 1st frame is displayed).

                0 = No info
                1 = Errors sent to DebugView window (Need DebugView Utility)
                2 = Warnings & Errors sent to DebugView window
                3 = Parsing Info, Warnings & Errors sent to DebugView window. 
                4 = Debug info, Parsing Info, Warnings & Errors sent to DebugView window (dll Testing, or just for your curiosity). 

                In DebugView, filter for "Prune:" to skip all the extraneous stuff generated by other plugins/programs.
                (On "Menu:Edit-Filter/Highlight", and enter "Prune:", all ClipClop messages are prefixed by "Prune:".


        NoErr,  bool, Default false

                false = Stop on ANY command error. (usual mode)
                     You will be informed in DebugView which (if any) errors can be ignored if switched to NoErr==true.

                true =  Suppress trivial errors where possible.
                     Only use after you have viewed and dismissed as unimportant any DebugView errors displayed when NoErr==false.
                     Not all errors are ignorable.

        Fade    float, Audio Fade Duration. Default 1.0 (1 millisecond).
                0.0 (off) to 25.0 = 25.0 milliseconds.
                Will be limited internally to 25.0 milliseconds or half frame duration, whichever is lesser.

        FadeIn  bool, Default false.
                false, no audio fade-in at start of output clip.
                true, fade-in audio at start of output clip.  (will switch internally to false if Fade==0.0)

        FadeSplice  bool, Default false.
                false, no audio Fade-Out/In at splices in output clip.
                true, Audio Fade-Out/In at splices in output clip. (will switch internally to false if Fade==0.0)

        FadeOut  bool, Default false. 
                false, no audio fade-Out at end of output clip.
                true, fade-Out audio at end of output clip. (will switch internally to false if Fade==0.0)

        Nickname String, default "" (not set) [Added v1.10].
                Nicknames representing a clip index eg 'Hols 37,2045' instead of '5 37,2045'.                

Prune is a simple plugin to trim() multiple source clips and splice the results into a new clip,
has Audio fade (to reduce clicks between spices) for supported audio formats.
The plugin will do AlignedSplice only.
All, the source clips must be in the same colorspace, same size as the first R0, source clip.
The audio must also be the same as the first R0 clip.

Prune will accept up to 256 source (Rx) clips, they are not named.
(Hopefully that is enough for those of you who are very demanding [You know who you are])  ;)
Source clips start at R0 and go up to R255.

Either the command file (Cmd) or the Command string (SCmd) must also be supplied.
*** NOTE ***,  if both Cmd and SCmd are supplied, the commands in the Command File are processed
first followed by those in the SCmd String, So if both are processed, all the trims in the command file
will be spliced together and those in the SCmd will be added later. It might be wise to use the SCmd
string when setting up your trims and then transfer them to the command file when happy. Then
continue adding trims to the end of the clip using the SCmd string, etc.

The Command file (Cmd) and the Command String (SCmd) will have a series of ranges to Trim, 
and will have the below format.


Where the 'R' is optional and can be omitted.

where x is clip index number eg R7 is clip 7, (the first one is R0).

Where the '(' and ')' are optional and if skipped then the opening '(' must be replaced by Comma ',' or ' ' (SPACE).

Where the ',' (COMMA) can be replaced with a ' ' (SPACE) [only needed if 'e' is specified].

Where the ')' is strictly speaking, unnecessary, whether the '(' is used or not.

s is the start frame and MUST be supplied.

e is optional and if missing, then the range will consist of only 1 frame.

        If e=0, then the range will continue to the last frame of the Rx clip.

        If e is -ve (negative) then it will represent a -ve frame count eg -2 means 2 frames.

These are all valid:

R0 (35,42)      # This is a comment
R1 65 374
2 1000
3 3700 5000
4 (36734,0)     # My helicopter is full of penguins

If the command file contained the above commands then clips R0 to R6 have all to be supplied to Prune.

The Cmd file commands MUST be line separated (ie one command per line).
The SCmd commands can be either Line Separated as the cmd commands or use a ';' SEMICOLON separator, as in

SCmd="R0(35,42) # My Zeppelin is full of lead ; R1 65 374
        R2,1000,1200; R2(1400,1500)
        R3(2000,-100)  # My Spaceship is replete with aardvarks"

In SCmd, A SEMICOLON ';' would not be acceptable in a comment, it would signify a new line and command pending
(ie PARSE error, it would look for a command following it).

  The term 'Rx' clip originated in sister plugin ClipClop where it meant 'replacement clip x',
it is kept in Prune for mutual compatiblity with ClipClop and so that future plugins might be able
to parse both Prune & ClipClop's command files including 'Rx nnn,nnn' type commands. 


v1.10, Nickname string is roughly the same format as SCMD, SEMICOLON (;) separated if on same line
or line separated, and can also contain comments. A Nickname, MUST start with either an underscore ('_'),
or an Alphabetic character ('A'-'Z' or 'a' - 'z'). The remainder of the nickname can contain underscore,
alphabetic or numeric ('0' - '9') characters, as in "_Testing_123_Testing" or "AnyOldName_432" or "Fred".
The length limit on Nicknames is 31 characters.
There are a set of RESERVED names that CANNOT be redefined by Nickname, "Rnnn" or "rnnn" where 'nnn' represents
1 or more numeric digits. In a command file/string, you can use eg "R0" to "R255" (or '0' to '255') to refer to
the clips whether or not they have nicknames applied.
As well as "(", "," and SPACE " " separators, a nickname allows "=". Below some valid examples:-

NickName = "
    Xmas_Crackers=1 #  This is a comment ; Vaca,2 # Costa Del Sol July 2006 ; Hols_Part_1(3) # Never again 
    Hols_Part_2(4 # Never say 'Never Again'.
    QP (6)   
    XXX 7 # Patient: My hand hurts when I do this. ; ttt = 8 # Doctor: Then stop doing that!
    ds123dgsdg__dld 9

Nicknames do not have to be in ascending order, but might be best to keep them that way.

Using above Nickname example,

"Hols_Part_1 2000,3000" would replace source frames 2000 to 3000 with clip 3 frames 2000 to 3000, when used in a command
file or command string. Nicknames are case insignificant ('A' == 'a').


If NoErr is true, then the plugin will try to avoid throwing an error for 'suspect' commands, not all
errors will be ignored.
Commands that do not fit in the valid formats described above will not be ignored (PARSE error). 
-ve start frame will not be ignored (PARSE error, it could be clipped to 0, but I REFUSE to allow it).
If an Rx clip has been omitted (missed out) then all Rx commands can be ignored.
If a range fully or partially falls outside of the source clips, then those can be ignored (invalid part of the range).

It is recommended that you DO use the linked DebugView utility, to check out warnings,
Prune() will try to warn you if you need to re-evaluate your,,, evaluations. 
There is no need to be alarmed by the NoErr option, you do not have to use it.
Dont always use NoErr = true, unless you really really know what you
are doing (or your name is 'Cretindesalpes' :)

The CMD and SCMD parsing is a 2 pass process, reason being, we need to know how many frames will
be generated, in order to allocate arrays to hold the trim data, So the 1st pass counts generated
frames, and the second pass allocates and fills in the arrays with the trims. Both passes will
produce output in DebugView, CMD, SCMD, CMD, SCMD.
In v1.02, trim/splice 'coalescence' has been implemented for adjacent trims from same source clip,
ie if a command file had the following in it:

0 (10,12)
0 (13,15)
0 (16,18)

then frames 10 through 18 would be amalgamated or coalesced as though from a single trim/splice.
This would be more conservative on memory requirements in Prune, and also avoid fading of audio between 
splices where there was clearly no need for such.

If you wanted (for whatever reason) to KEEP some frames in a clip based purely on some runtime
filter, eg YDifferenceFromPrevious, then you might be able to use something like this:

    # Template, to KEEP frames where YDifferenceFromPrevious is greater than 0.1 (delete those that are less than).
    # The '|| current_frame==0' part of the condition is required for the first frame as it always results in 0
    # using YDifferenceFromPrevious on frame zero.
    # Could use other conditionals to keep/delete for other applications.

    Avisource("In.avi").ConvertToYV12() # Ensure Planar for YDifferenceFromPrevious (not necessary for Prune pass).
    assumeFPS(250.0)    # Fast as we can
    Writefileif("In_cmd.txt","YDifferenceFromPrevious>=0.1 || current_frame==0",""" "0," ""","current_frame",append=false)

And for the 2nd pass for Prune(),

    Avisource("In.avi")     # ConvertToYV12(), Not Necessary here.

The first Writefile pass might produce a command file listing for Prune(), like this:


Where in this case frame two was omitted. All the initial zeros specify clip zero as the source clip for each of
these single frame trim/splices, and the second number is the frame number. When fed into Prune(), the first two
frames 0 and 1 will be coalesced into a trim and likewise the frame 3 and 4 into another trim as if these were specified
in the command file as:

   0,0,1    # first trim
   0,3,4    # second trim

I have tested the speed at which Prune() can do it's two pass parse on a command file of 30,000 frames, 42 of which were
omitted by the writefile script and the input of 30,000 single frame trims was coalesced to 8 trims overall
with an overhead of about 1.5 seconds on my less than powerful machine. In most cases, I think you are unlikely
to be wanting to feed in 30,000 or more trims to Prune, but the above example shows it can be done without effort.
Above timing was with dv=0, ie DebugView output off (a couple of seconds longer with full debug on).

Just a little idea of where this might be useful, security cameras where you want just the interesting bits
and omit the masses of static frames that are of no interest but you might want to raise the condition above 0.1 as
used above to avoid false alarms.


Almost all of the hard work of Prune is done during setting up the filter. During the rendering
stage, Prune() does not do anything terribly clever, it just selects the frame to use from
pre-calculated arrays, what it does do, it does fast as possible. Prune() has an overhead of approx
1 trim or splice filter, no matter how many trim/splices are involved, if you are processing eg
30000 single frame trim/splices it should be somewhat faster than if you had to do it in script.

[edit] Examples


[edit] Changelog

v0.00Alpha - First release, testing 123.
v1.00 - 19 Sept 2011, Fixed bug in GetAudio().
v1.01 - 03 Nov  2011, Fixed bug 'Rx(0)', interpreted as 'Rx(0,0)' [whole clip], rather than 'Rx(0,-1)'. 
	Added FadeIn/FadeSplice/FadeOut
v1.01beta2 - 05 Nov 2011, Added bool args, FadeIn, FadeSplice, FadeOut.
v1.02 - 17 Nov 2011, args FadeIn, FadeSplice, FadeOut all now default false.
	Added '\n' to all debug output strings.
	Now coalesces adjacent trims from same source clip.
27/Mar/2012 - ver 1.10      - Added Nicknames.
30/Mar/2015 - ver 1.11 - Added v2.6 dll. Shows Nicknames when Show.
01/Apr/2015 - ver 1.12 - Display Nicknames in original casing when Show.
20/Dec/2018 - ver 1.13 - Moved to VS2008, Add x64.

[edit] Archived Downloads

Version Download Mirror

[edit] External Links

Back to External Filters

Personal tools