########################################################################
#       RiffWorks Hacks -- Documentation (geared towards MacOSX)       #
########################################################################

DISCLAIMER:

  - This stuff is unsupported!!!

  - Always take backups and test whether your changes work and keep
    working like expected! And keep the backups! Don't throw 'em away!!

  - I didn't put any effort (yet) in catching errors or wrong usage,
    so use it like it should!

  - I actually don't know a lot about WAVE files, but hey, this tool
    seems to work for me :-)

  - If you like the software, want extra features, want extra support
    or are way to rich, please give me one, a couple, or a lot of euros
    (or whatever currency) on my paypal to support development and make
    it able for me to buy the full version of RiffWorks ;-) (PP account
    is jimmy#inet-solutions#be .. replace first '#' with '@' and the
    second with '.' (DUH)).... I can try, right? ;-)

########################################################################

Requirements:

  - Any UNIX/Windows based OS will do, but it's developed for OSX.

  - Terminal emulator (with shell ... duh):
     * OSX has /Applications/Utilities/Terminal.app by default.
     * Windows has cmd.exe by default.
     * UNIX/Linux users should know what I'm talking about.

  - Python
     * My OSX 10.4 has it by default.
     * Windows can install ActiveState ActivePython.
     * UNIX/Linux users should know what I'm talking about.

  - Tools to zip/unzip files.

  - Knowledge on how to use interactive shells and UNIX.

########################################################################

What you should know about RWS/RWR files:

They are just ZIP files with a '.rwr' or '.rws' filename extension
instead of the usual '.zip'. As far as I know they should be and
should stay uncompressed for performance reasons.

Take a good look at the folder structure if you put them back into a zip
archive. Don't put them into another folder when archiving because you
will get something like a "can't find song" error message.

You will see '.rif' files that contain all the info and '.psi' files
that contain all wave frames.

Take good backups when you are going to do these unsupported things!
After you made your changes you should let it loop a few times to check
if the timing IS and STAYS correct.

Take a good look at the '.rif' file as it contains the info on which
'.psi' files are actually used. If you are careful you can move and/or
duplicate layers to other riffs but be careful with the timing/length.

The '.psi' files are just WAVE frames, and AFAIK they are always 16bit
stereo at a sample rate of 44,1kHz. Always check when you replace files,
you replace them with files that have the same amount of WAVE frames
or you'll have to pad them with empty WAVE frames until you have the
required amount of frames to be able to replace them.

########################################################################

Installation:

  - Download http://pub.devbox.be/devel/riffhax/riffhax.py.txt

  - Rename the file to riffhax.py and put it in a directory in your PATH
    or live with it by running it from the current working directory.
    
    On OSX you'll need to open Terminal.app and if the file is on your
    desktop you can use these commands (don't type the '$', it just
    tells you I am typing in the termanl):
    
        $ cd ~/Desktop
        $ chmod 755 riffhax.py
        $ mv riffhax.py /usr/bin/

    Yes, I'm sorry, but for now you'll need to have some UNIX knowledge
    to be able to use it as I don't know whether people will actually
    use it and/or like it. Who knows the next RiffWorks version is going
    to support this kind of stuff.

########################################################################

Help:

  - To display the help, just type 'riffhax.py' in your terminal and
    you'll see something like below. In the next sections I will discuss
    each action in another order.

    Display file info:
        riffhax.py wavinfo <wav_file>
        riffhax.py psiinfo <wav_file>

    Convert between psi and wav:
        riffhax.py wav2psi <wav_file> <out_file>
        riffhax.py psi2wav <psi_file> <out_file>

    Add empty padding frames:
        riffhax.py wavpad <wav_file> <out_file> <pre> <post>
        riffhax.py psipad <psi_file> <out_file> <pre> <post>

    Copy frames to new file:
        riffhax.py wavcpy <wav_file> <out_file> <first> <last>
        riffhax.py psicpy <psi_file> <out_file> <first> <last>

    Calculate number of frames:
        riffhax.py frames <num_bars> <bpb> <bpm>

    List rwr/rws file structure:
        riffhax.py rwlist <rw_file>
        riffhax.py rwlistall <rw_file>

    Unpack rws/rwr file (external):
        unzip <rw_file> -d <new_or_empty_dir>

    Pack rws/rwr file (external):
        cd <unpacked_dir> && zip -0r <new_rw_file> * -x '*.DS_Store'

########################################################################

EXAMPLES #1:

    Lets list the content of our .rwr file:
        $ riffhax.py rwlist my-project.rws
        File: my-project.rws
                riffs/
                riffs/riff1_A/
                riffs/riff1_A/6-21-2009_20252982431_0.psi
                riffs/riff1_A/riff1_A.rif
                riffs/TAPERIFF/
                riffs/TAPERIFF/TAPERIFF.rif
                song.sng

    More detailed info can be displayed using:
        $ riffhax.py rwlistall my-project.rws
        [output not shown]

    Note: unzip/zip are external commands.

    Unpack an rws/rwr file to a new directory called 'foo':
        $ unzip my-project.rws -d foo
        Archive:  my-project.rws
           creating: foo/riffs/
           creating: foo/riffs/riff1_A/
          inflating: foo/riffs/riff1_A/6-21-2009_20252982431_0.psi
          inflating: foo/riffs/riff1_A/riff1_A.rif  
           creating: foo/riffs/TAPERIFF/
          inflating: foo/riffs/TAPERIFF/TAPERIFF.rif  
          inflating: foo/song.sng            

    Pack it to an rws/rwr file again:
        $ cd foo && zip -0r ../my-project2.rws * -x '*.DS_Store'

########################################################################

EXAMPLES #2:

    Display WAV file info:
        $ riffhax.py wavinfo ~/Desktop/take001.wav
        File: /Users/jimmy/Desktop/take001.wav
                Channels: 2
                Sample Width: 2
                Sampling Frequency: 44100
                Number of Audio Frames: 705600
                Compression Type: NONE
                Compression Name: not compressed

    Display PSI file info:
        $ riffhax.py psiinfo foo/riffs/riff1_A/6-21-2009_20252982431_0.psi
        File: foo/riffs/riff1_A/6-21-2009_20252982431_0.psi:
                Size: 2822400
                Assumed Frames: 705600 (2822400 / 2 / 2)

########################################################################

EXAMPLES #3:

    Convert .psi (file.psi) file to .wav (new-file.wav):
        $ riffhax.py wav2psi file.psi new-file.wav
        Written to new-file.wav

    Convert .wav (file.wav) file to .psi (new-file.psi):
        $ riffhax.py psi2wav file.psi new-file.wav
        Written to new-file.wav

########################################################################

EXAMPLES #4:

    Add 0 empty frames before and 1000 after and save to a new wav file:
        $ riffhax.py wavpad file.wav new-file.wav 0 1000
        Written to new-file.wav

    Add 100 empty frames before and 900 after and save to a new psi file:
        $ riffhax.py psipad file.psi new-file.psi 100 900
        Written to new-file.psi

########################################################################

EXAMPLES #5:

    Copy frame 1 to 352800 from a wav to a new wav file:
        $ riffhax.py wavcpy file.wav part-file.wav 1 352800
        Written to part-file.wav

    Copy frame 352801 to 705600 from a psi to a new psi file:
        $ riffhax.py psicpy file.wav part-file.wav 352801 705600
        Written to part-file.psi

########################################################################

EXAMPLES #6:

    How many frames 8 bars at 120bpm having 4 beats per bar takes:
        $ riffhax.py frames 8 4 120
        8 Bars, 4 Beats Per Bar, 120 Beats Per Minute = 705600.000000 Frames

########################################################################