perlyVFX
========

(C) hans artmann, 2001-2003
hans-artmann@t-online.de

1. What's perlyVFX
2. Files
3. Usage
4. Software and system requirements
5. Conditions of usage and redistribution

1. What's perlyVFX
=================

perlyVFX is a bundle of perl scripts to deal with VFX sysex files.
It provides basic functions to analyze the contents of sysex
files for both single programs and banks and to extract information like
program names, parameters, waves used, etc. 
The output are text files in CSV format which can easily be imported
into databases or spread sheet programs like MS Access and Excel.

Patches can be compared and all differences will be documented in a
text file.
This gives you the chance to decide if e.g. programs with he same name 
are really equivalent. If not you can see where they are different.
Also identical programs with different names can be detected.

perlyVFX is not an archive. I use the well known programs SOUNDLIB and
VFXLIB to dump, store, and rearrange my sysex files.

The package is supplemented by an MS Access database which makes it easy
to sort, filter, and view information on your patches. You can e.g. see
for each program which wave forms are used in any combination of the
patch select switches.

2. Files
========

Descriptive files:
------------------
You would not like to read any of these files except the readme.txt unless you want
to change or extend the programs.
 
readme.txt		this file
allProgramsStruct.txt	describes the data structures found in VFX
			sysex files and used within perlyVFX
waves.txt		assigns wave numbers to wave names
pack.txt		describes how the perl functions pack and unpack work
patchValues.txt		assigns pach numbers to their binary representation
effectpars.xls		analysis on how effect parameters are mapped in the bit arrays

Perl scripts:
-------------
vpcheck.pl		prints from a sysex file the names of programs, a unique 
			checksum for the 6 voices, and a unique checksum for the 
			program parameters of each patch.
			If two programs have the same checksums this means they
			are identical even if they have different names.

			Syntax: perl vpcheck.pl sysexfile [> output-file]
			
 
vpcheckdir.pl		like vpcheck.pl, but works on all files of a directory. The
			first line is a header with the field names.
			You can e.g. import the created file into Excel or another 
			spread sheet program for further analysis.

			Syntax: perl vpcheckdir.pl [directory] [> output-file]

			If <directory> is not specified the current directory will
			be searched.

progcomp.pl		compares 2 specified programs in one sysex file.
			All voice and program parameter names are listed where a difference
			between the the two programs has been found. The values of
			the parameters will not be printed, so there is no reference
			to the either of the two programs.
			If the specified programs are identical the list will be empty.

			Syntax: progcomp.pl sysexfile patchnum1 patchnum2  [> output-file]

			Use patch numbers as printed in the output files (1-60) in
			ascending order.


voices.pl		prints from a sysex file the names of programs and a 
			unique checksum for the 6 voices of each program.

			Syntax: perl voices.pl sysexfile [> output-file]

voicedir.PL		like voices.pl, but works on all files of a directory

			Syntax: perl voicedir [directory] [> output-file]

			If <directory> is not specified the current directory will
			be searched.

sdvoicedir.PL		like voicedir.pl, but restriczs output to program containing waves
			that are only available on a VFX-SD

			Syntax: perl sdvoicedir [directory] [> output-file]


[test.pl		test program to check how pack and unpack works]

Libraries (Perl packages):
--------------------------
vfx.pm			provides vfx specific sub procedures
waves.pm		vector to assign wave names to wave numbers (currently VFX only)
vfxprogpars.pm		vector to assign parameter names to program parameter values

Output examples:
----------------
vpcheck_effects.txt	output created by vpcheck.pl
vpcheckdir.txt		output created by vpcheckdir.pl
progcomp.txt		output created by progcomp.pl
voices_test.txt		output created by voices.pl
voicedir.txt		output created by voicedir.pl
sdvoicedir.txt		output created by sdvoicedir.pl


Database:
---------
vfx1.mdb		MS Access 97 database

[file.tst		test file: contains all chars from 0-255]

3. Installation and usage
=========================

To use the perl scripts you must have a perl interpreter installed on
your system (see next section).
The .pl and .pm files must be located in the same directory, e.g.
C:\perlyVFX. This directory must be added to your PATH as well as the
PERL directory by adding a line to your autoexec.bat similar to:
SET PATH=C:\PERL\BIN;C:\perl2exe;C:\perlyVFX;"%PATH%"

It's simple and safe to unpack all perlyVFX files to one directory
and use this as the working directory, i.e. the sysex files and directories
to this location too.

You may then run the scripts either from the command-line in a CMD
(MS-DOS prompt) window.

For the description of what the scripts do see section 2. Files.

Use the syntax given in section 2 and in each script file.
Normally the scripts take a the file or directory name as an argument. 
The output goes to standard output which usually is the screen and
can be redirected into a file for further processing. 


4. Software and system requirements
===================================

perlyVFX is supposed to run on any Win32 system like 95, 98, ME, or XP.
The perl scripts rely on ActivePerl Build 555 or later. This is a Win32
perl interpreter which is available for free from 
www.ActiveState.com/ActivePerl

You should be aware that a licensed version of MS Acess 97 is required
to use the database.


5. Conditions of usage and redistribution
=========================================

I provide perlyVFX for free. The only conditions I would like you to
agree to are:

a. If you redistribute the files please forward the complete package 
   with my copyright in it.
b. If you make any changes, amendmends, and improvements please document
   them in the files and let me share a copy!

I know this is not a very user friendly description for an even more unfriendly
user interface. I just tried to create something which would help me dealing with
hundreds of VFX programs - and it works for me.
 
If you have problems with Perl installation or usage please let me know.  

Have fun!

  
