test not only if header frei0r.h exists, also use an item

[mlt-frei0r-support.git] / shotcut / README

README
------

        The applications defined in this project are as follows:

        * shotcut-wm      : The shotcut window manager
        * shotcut-server  : The main shotcut server
        * shotcut-inject  : Transmit westleys without modification
        * shotcut-preview : A media player
        * shotcut-editor  : A text editor tailored for westley documents
        * shotcut-nle     : The shotcut non-linear editor


PRE-REQUISITES
--------------

        The shotcut suite is dependent on the following:

        * mlt
        * mlt++
        * fltk 1.1.x

        Some of the default behaviour relies on:

        * gnome-terminal
        * mc
        * mactor
        * mcmlt

        It's not essential for these to be installed though.


INSTALLATION
------------

        To configure and build the environment, run:

                ./configure
                make
                sudo make install

        To set up an environment for use, please read the rest of this document.


GENERAL
-------

        Most shotcut applications have a server in them. These servers allow input to
        be received in the form of MLT westley documents. 

        When a document is received, they typically carry out an action - for example
        the text editor will show the document and allow you to edit it, the preview
        will play it and the shotcut server will pop up a dialog asking what you want 
        to do with the document by presenting a list of possible destinations.

        The usage of the tools and details on how to integrate other tools into the 
        shotcut framework is provided below.


TERMINOLIGY AND CLASSIFICATION
------------------------------

        For the purpose of this document, the following terminoligy will be used:

        client         : Any application which generates the DVCP PUSH
        server         : Any application which responds to the DVCP PUSH
        window manager : The window manager in use (not necessarily shotcut-wm)

        All MLT applications which allow the use of the 'valerie' consumer are 
        clients.


SHOTCUT-WM
----------

        The shotcut window manager provides a system administrator with the option to 
        set up a totally closed session for use of the shotcut tools. Since it is very
        light on resources and imposes a bare minimum of start up processes, this is a
        good option for production use of shotcut.

        It provides:

        * a multi-workspace window manager
        * a mechanism for specifying start up applications and their workspace
        * a never obscured utility panel (for switching workspace and logout)

        NB: shotcut-wm does not provide any mlt specific functionality - it is neither
        a server nor a client. Its usage is not a pre-requisite for using the shotcut
        tools.

        To use it, you need to carry out the following steps:

        1) Create a new user which uses the shotcut-wm
        2) Customise the start up profile

        The following creates a new user for Mandrake 10 - other distros may require
        slightly different operations:

                cd shotcut
                sudo /usr/sbin/useradd shotcut -m -k home
                sudo passwd shotcut

        To test the user while still running your original X session, run:

                gdmflexiserver

        IMPORTANT NOTES:

        1) Make sure that no shotcut servers are running in your current X session 
           first. The ports the tools run on may clash and hence cause your new 
           users tools to fail to start or start incorrectly.

        2) You can switch back to the original X session by using Ctrl Alt F7 and
           you will automatically return when you logout of the session. Note that 
           the original session will present you with a back screen - this is OK,
           just press a key or move your mouse to be presented with a dialog to 
           redisplay the original session.

        3) You may not get audio in the second session due to permissions on the 
           dsp and/or alsa devices. Try: chmod a+w /dev/dsp /dev/snd/*

        When you login, you will be presented with the default session - this isn't
        a well managed session as no window geometries are specified.

        You should find:

        * Workspace 1 contains a maximised mainactor;
        * Workspace 2 contains a terminal with mc running, preview and text editor;
        * Workspace 3 contains the NLE.
        * Workspace 4 is empty.

        You can switch between workspaces using:

        * Using the buttons on the panel
        * Ctrl-F1 to Ctrl-F4
        * Ctrl-Alt-Left and Ctrl-Alt-Right

        There is also a 'hidden' shotcut-wm menu which can be activated by:

        * Alt-Escape
        * Ctrl-Alt-Escape will activate the menu as per the original flwm behaviour

        The windows created on start up are managed via $HOME/profiles/shotcut.  You 
        can edit this file to specify which tools are autostarted. 

        An example profile is as follows:

                0=gnome-terminal &
                .workspace=2
                .windows=1

                1=shotcut-server &
                .workspace=2
                .windows=2

                2=shotcut-nle &
                .workspace=3
                .windows=1

                3=mactor &
                .workspace=1

        Note that you need to specify the workspace the tool appears on and the number 
        of windows the tool creates when it starts up - the shotcut-wm will wait for 
        these windows to appear before moving on to the next command. If the last tool 
        starts on workspace 1 (as in the example above), then the number of windows is 
        unimportant since the window manager will remain on the first workspace.

        You may specify starting geometry for the tools using the command line switches
        of the tool. 

        Shotcut tools typically take a -g WxY+x+y geometry argument, though 
        shotcut-server is a special case - it has its own profile and you need to 
        specify its tools and geometry there. Take care when customising shotcut-server
        since you will need to specify the number of windows it generates in this 
        profile.


SHOTCUT-SERVER
--------------

        This process is designed to control your desktop.  It acts as a proxy for a 
        configurable collection of miracle server applications.

        Typically, shotcut will run on the default miracle port (5250) and the default
        behaviour for all clients will be to send documents to this process.

        To run shotcut in its default mode, you would simply run:

                shotcut-server

        The default behaviour is to:

        * start the shotcut-server on port 5250
        * start a basic gui profile with the following tools
                * shotcut-preview on port 5251 
                * shotcut-editor on port 5252

        To quickly test your environment, try:

                shotcut-inject noise:

        and select a destination from the menu provided. Notice that the menu always
        appears immediately under the mouse and has the keyboard focus. You can use 
        the cursor keys to move between the options, and pressing 'space' will 
        select it.

        You can configure the tools that the server creates and feeds by creating a 
        'profile' and specifying this when you start the server.

        An example profile might contain something like:

                # Defines the number of tools
                tools=5

                # Define each tool using the following syntax:
                #
                # n=Name
                # .command=command
                # .port=port|server|server:port
                #
                # Note that commands should background themselves (include a trailing & if 
                # the process doesn't fork automatically). You don't need to include a 
                # command, but a port is needed. 

                0=Preview 1
                .command=shotcut-preview -g 330x283+610+20 --on-top
                .port=5251

                1=Preview 2
                .command=shotcut-preview -g 330x283+970+20 --on-top
                .port=5252
 
                2=Editor
                .command=shotcut-editor -g 670x400+610+390
                .port=5253

                3=NLE
                .port=5260

                4=Miracle
                .port=playout

        This profile defines two previews, a text editor and links to a running
        instance of shotcut-nle and a miracle instance running on another server 
        (the default action is to append the westley to unit 0's playlist).

        To use this, you would save the file somewhere and run shotcut as:

                shotcut-server --profile=/path/to/your-profile

        It is possible to have multiple shotcut-servers running, each controlling
        their own set of tools and allowing connections to be established between
        them in either way. To do this, you should specify a different port using
        the --port=XXXX switch on the second instance and register the servers as
        tools in their profiles as required - this facilitates multiple window 
        manager work spaces having their own controlling server.


SHOTCUT-INJECT
--------------

        The shotcut-inject utility is a lightweight client.

        The simplest example of use is:

                shot-inject clip.dv

        This will send an westley which refers to the clip to the default server. 
        You may target a specific server via the --port=XXX switch if you wish.


SHOTCUT-PREVIEW
---------------

        This server provides immediate playback of all documents received. There is 
        transport functionality to allow you to pause, fast forward, rewind or scrub.

        Note that when you submit documents with the same 'title' property, the 
        position and playout speed don't change.

        The default behaviour of shotcut-preview is to open a small window directly 
        under the mouse pointer, but this can be overridden by specifying a geometry 
        via the -g switch.

        It can be controlled via:

        * The transport controls and scrub control situated at the bottom of the 
          window;
        * The left and right cursor keys can be used to do frame accurate scrubbing.

        Note that when you switch from normal playback, the display will show a low
        quality image. This is done to ensure minimal cpu usage. It will also 
        automatically pause when you switch workspace.

        Other switches are:

    * --name=name to specify how the server identifies itself;
        * --port=XXXX to specify the port to listen on;
    * --on-top to indicate that you want to start the preview as 'always on top';
        * --maximize to indicate that you want to start the preview maximized.

        The preview also has drag n drop support. Currently, only nautilus has been
        tested, but other file managers should also work.


SHOTCUT-EDITOR
--------------

        The shotcut-editor is a text editor provided in the fltk demo directory. It's 
        been adapted to handle westley syntax colouring and other features.

        On receipt of a new document, the editor will either place the new document in
        the text buffer directly, or, if the current contents have been manually 
        changed, you will be presented with a dialog to accept, save or cancel.

        Another feature is the ability to transmit a modified document into another 
        process - by default, shotcut sets this up so that it fires the doc back to 
        the main shotcut server and the options are all but the Editor itself (ie: you
        can select Preview or Cancel).


SHOTCUT-NLE
-----------

        This tool provides the main multitrack editing environment and is both a server
        and a client. It is designed to run in its own workspace.

        The main screen consists of 4 areas:

        +-------------+---------------+-------------+
        |Browser      |Preview        |Panel        |
        |             |               |             |
        +-------------+---------------+-------------+
        |Multitrack                                 |
        +-------------------------------------------+

        The workflow is as follows:

        * All westley documents submitted to the NLE will appear in the browser - 
          these are decorated with a thumbnail and sorted by order of addition

                * Above the browser, there are four 'light' buttons labelled as Projects,
                  Stories, Audio and Stills. When the light is on, input of that type
                  is shown, when off, they're removed from the view. Double clicking
                  on a button will turn off all other buttons.
                * Below the browser is a button labelled 'Clean' - this will remove 
                  all items in the currently selected view which do not exist in the 
                  project.

        * Selection from the browser by dragging allows you to immediately place a 
          clip on the multitrack (dropping the clip anywhere other than on the 
          multitrack acts as a cancel)

        * Selection from the browser by clicking will cause the selected clip 
          to open in the preview

                * Cursor up and down cause the next and previous item to be shown in
                  the preview.
                * Ctrl-enter key will attempt to insert the item in to the selected 
                  track of the multitrack, and will cause the timeline position to move
                  to the end of the inserted item. The next item in the browser is
                  automatically selected.

        * The preview provides playback by use of the 'transport buttons' below the
          display area. Play and pause can also be toggled by pressing the space bar.

                * At the bottom of the preview is a 'cutting' tool - this will allow you to
                  cut the clip by specifying in and out points, and from there, you can
                  drag the cut on to the multitrack
                * Any cuts from that clip which are already on the multitrack will be 
                  highlighted as a dull red, thus allowing easy reselection - reselection
                  will cause the reselected cut to turn bright red
                

        * The Panel allows you to edit attributes, titles and obscuring masks for the 
          current cut - these become attached to the cut and are automatically applied
          to the timeline
        
        * The default timeline consists of 4 manipulable tracks (1 for the main 
          video/audio, 1 for 'super text' and another 2 for audio mixing). Instances 
          of cuts from the currently selected clip are highlighted and a special 
          highlight is used to indicate the position of the current cut. Neighbouring 
          cuts from different clips have a transition between them.

        * You may also select to 'publish' the current project (push it to a specific
          miracle server for playout) or switch to another project.

        TO BE CONTINUED...


MISCELLANEOUS
-------------

        You can configure your environment so that the default consumer is 'valerie':

                export MLT_CONSUMER=valerie

        So when you run a command like:

                inigo "+Hello World.txt"

        The normal behaviour is to send it to the default server. You can override this 
        by specifying a -consumer switch if needed.

        Further to this, you can configure your file manager to default double clicks
        on media to 'inigo -consumer valerie' (or simply inigo if you set MLT_CONSUMER
        in your shell profile) or shotcut-inject. This provides nice integration with 
        existing tools such as nautilus, mc or konqueror.

        Standard JKL key bindings can be turned on by running:

                export SHOTCUT_JKL=true

        prior to starting shotcut-nle.