Overview
========

sodium is designed to be a dvd cover art viewer and movie launcher.


Usage
=====

Basic usage is: sodium /path/to/images size [/path/to/videos]

/path/to/images is the location of the cover images.

size is the size of the window to display in pixels. It should be at least 
300 and be a multiple of 300, e.g 300, 600, 900 etc

You can optionally specify a path to videos that can be played when clicking
on an image. See below.

It loads a 3 x 3 grid of images each at size / 3 squared pixels. E.g if you
specified a size of 900 the images would be 300x300 each.

You can navigate via the following:

	Keys

	Escape, q			Quit
	Page Up, Up Arrow		Page Up
	Page Down, Down	Arrow		Page Down
	Home				First Page
	End				Last Page
	c				Toggle cursor on/off
	1 to 9				Select Video
	s				Sort mode

You can also scroll with the mouse wheel. NOTE: Mouse scroll events are limited
to 1 scroll event every 750ms to prevent over scrolling on devices such as
trackpads.

You can also click on an image or press 1..9 (telephone layout) to have the
video for that played (if it's available).


Configuration
=============

Currently this is done through a mapping file that maps image names to video
names and the player to use and the arguments to pass to the player.

It takes the form of a pipe (|) seperated fields flat file, e.g one entry
would look like:

	taken.jpg|action/Taken.mkv|vlc|--fullscreen|6453

taken.jpg 		is the name of image shown in sodium
action/Taken.mkv 	is the relative path to the video
vlc			is the command to lauch to play the video
--fullscreen		is the arguments to pass to the video player
6453			is the movie runtime in seconds

The last field (runtime) is optional.

When specifing a relative path you have to pass the optional /path/to/videos
argument that is the top level directory where the videos are held. NOTE: you
can only pass in one of these.

Alternatively you can specify absolute paths (starting with a '/').

In the mapping file you can also specify multiple space seperated video paths,
e.g

half_past_dead-half_past_dead_2.jpg|action/Half_Past_Dead.mkv action/Half_Past_Dead_2.mkv|xine|-f

Again these paths can either be relative or absolute. Both paths will be passed
to the launched command. This is perhaps useful where you have a box set
containing a number of movies.

If you have a box set of a series for example. You can do something like

24_season_4.jog|series/24/Season_4/|nautilus|

which would bring up a nautilus window showing the contents of the Season_4
directory.

If you specify the optional runtime field then when pressing 's' sodium will
cycle between sorting by movie name (default) and sorting by runtime in
ascending order. Entries with no runtime field will be treated as 0.

There is a tools/add-runtimes.sh script to help in adding runtime entries to
an existing mapping file.

The mapping file should be called movie-list and placed under
~/.config/sodium/


Animation
=========

When the mouse moves over an image, the image will start rotating. Clicking
it will launch the movie.

You can disable the animation by setting the SODIUM_ANIMATION environment
variable to 0. e.g

	$ export SODIUM_ANIMATION=0
or
	$ SODIUM_ANIMATION=0 sodium <args ...>


Debug output
============

Debugging output can be enabled by setting the SODIUM_DEBUG environment
variable to 1.

License
=======

Sodium is licensed under the terms of the GPLv2. See the COPYING file.


Contributing
============

See CodingStyle. Also, code should be signed-off. This means adding a line
that says "Signed-off-by: Name <email>" at the end of each commit, indicating
that you wrote the code and have the right to pass it on as an open source
patch.

See: http://developercertificate.org/