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.

