-----------------
DEBUGGING OPTIONS
-----------------
If you run lyricue or lyricue_server with -d then debugging is on.
Also by default debugging information is logged to ~/.local/share/lyricue/frontend.log and server-<port>.log where <port> is the portnumber that the server is listening on

--------------------------------
NETWORK COMMUNICATIONS INTERFACE
--------------------------------

This document describes the Client<->Server communications.
By default the server opens a socket on port 2346 on localhost.
The preview window opens a socket on port 2347 on localhost.
The miniview window opens a socket on port 2347 on localhost.
All communications are initiated by the client.
The format for sending messages is <command>:<first parameter>:<second parameter>
Communications are not case sensitive other than filenames/db names

Commands
--------

Command - 'query'
First parameter - database to query (lyricDb/mediaDb/bibleDb)
Second parameter - SQL query
Purpose - To do a SQL query and return results in JSON format
Response - JSON formatted results
Example - 'query:lyricDb:SELECT * FROM playlists'

Command - 'osd'
First parameter - slow,fast,time in milliseconds or left blank
Second parameter - OSD text to display
Purpose - To display scrolling text at bottom of screen
Response - ""
Example - 'osd:4000:sample text'

Command - 'status'
First parameter - previewon|previewoff|blank
Second parameter - not used
Purpose - To find out server width/height/font and tell server if previews wanted
Response - "Status,W:<width>,H:<height>,F:<font>"
Example - 'status::'

Command - 'reconfig'
First parameter - not used
Second parameter - not used
Purpose - To reload the Configuration
Response - "Configuration reloaded"
Example - 'reconfig::'

Command - 'backdrop'
First parameter - image filename to load - or 'special;v4l' for live video
Second parameter - not used
Purpose - To change the background to the file given, 
First parameter - image filename to load, image must be in backgrounds directory
Response - "Backdrop changed to <filename>"
Example - 'backdrop:lds.xpm:'

Command - 'blank'
First parameter - image to use as background - leave blank if only clearing text
Second parameter - not used
Purpose - To blank the screen
Response - "Screen blanked"
Example - 'blank::'

Command - 'change_to_db'
First parameter - Bible database name
Second parameter - not used
Purpose - Change the bible database to a different version
Response - "DB changed to <Database name>"
Example - 'change_to_db:nivDb:'

Command - 'display'
First parameter - 'p'
Second parameter - pagenum to preview
Purpose - Preview a single page without adding to playlist
Response - "Displaying <title> page <page>"
Example - 'display:p:123'

Command - 'preview'
First parameter - 'header:author:copyright:nowrap' if 'nowrap' not included then assumes word wrapping
Second parameter - 'text'
Purpose - Show given text directly
Example - 'preview:header:text:nowrap'

Command - 'display'
First parameter - 'current'
Second parameter - ''
Purpose - Redisplay the current page
Response - "Displaying <title> page <page>"
Example - 'display:current:'

Command - 'display'
First parameter - 'next_page'
Second parameter - 'loop;parent_id' or ''
Purpose - Display the next page. If the second parameter is 'loop' then loop to first page if currently on last page.  If parent_id is set then loop that sublist
Response - "Displaying <title> page <page>"
Example - 'display:next_page:loop'

Command - 'display'
First parameter - 'prev_page'
Second parameter - 'loop' or ''
Purpose - Display the previous page. If the second parameter is 'loop' then loop to last page if currently on first page
Response - "Displaying <title> page <page>"
Example - 'display:prev_page:'

Command - 'display'
First parameter - 'next_song'
Second parameter - not used
Purpose - Display the next song in the playlist
Response - "Displaying <title> page <page>"
Example - 'display:next_song:'

Command - 'display'
First parameter - 'prev_song'
Second parameter - not used
Purpose - Display the previous song in the playlist
Response - "Displaying <title> page <page>"
Example - 'display:prev_song:'

Command - 'display'
First parameter - 'page'
Second parameter - page number in current song
Purpose - Jump to a particular page in a song
Response - "Displaying <title> page <page>"
Example - 'display:page:3'

Command - 'display'
First parameter - playlist item number
Second parameter - not used
Purpose - Jump to a particular item in the playlist
Response - "Displaying <title> page <page>"
Example - 'display:12:'

Command - 'get'
First parameter - playlist
Second parameter - playlist name
Purpose - Get the contents of a playlist
Response - PLaylist contents
Example - 'get:playlist:Main'

Command - 'get'
First parameter - playlists
Second parameter - not used
Purpose - Get a list of Playlists
Response - List of playlists
Example - 'get:playlists:'

Command - 'get'
First parameter - status
Second parameter - not used
Purpose - Get current server status
Response - <current_playlist>:<current_item>:<current_point>
Example - 'get:status:'

Command - 'media'
First parameter - pause
Second parameter - not used
Purpose - Pause playing video
Response - 
Example - 'media:pause:'

Command - 'media'
First parameter - skip
Second parameter - position in seconds
Purpose - Skip to position in video
Response - 
Example - 'media:skip:10'

Command - 'bible'
First parameter - available|maxchapter|maxverse|verse
Second parameter - none|book|book chapter|verse reference
Purpose - Control Bible access
Response - 
Example - 'bible:maxverse:John 3


-------------------------
CONFIGURATION FILE FORMAT
-------------------------

The configuration file is in /etc/lyricue/default.conf initially but used
from ~/.share/local/lyricue/config2 for each user
Following is a description of each possible line.

'Main'     - Font used for main lyrics on server
'Header'   - Font used for header section on server
'Footer'   - Font used for footer section on server
'Colour'   - Colour used for text on server (hex value)
'ShadowColour' - Colour used for text shadow (hex value)
'ShadowSize'   - Num of Pixels that shadow is moved down/right of text
'Height'   - Window height for server/interface
'Width'    - Window width for server/interface
'OverscanH' - Size of border that is not written to in server
'OverscanW' - Size of border that is not written to in server
'Loop'     - Boolean state of looping (ie. if you press next at the last
             page should it return to the first page)
'Audit'    - Should song adds/removes be audited (for song usage tracking)
'DynamicPreview' - Boolean state of preview window
'MiniView'   - Boolean state of miniview window
'Xinerama' - Boolean state of xinerama
'VerticalLocation' - Vertical text location (Top, Bottom, Centre)
'HorizontalLocation' - Horizontal text location (Left, Right, Centre)
'Justification' - Text justification (Left, Right, Centre)
'BGImage'  - Filename of default background image
'SpecialSong' - Song that will sit at top of available songs always
'SpecialImage' - Image category that will be selected by default
'SpecialBack' - Background category that will be selected by default
'ImageDirectory = /home/cjd/Desktop
'BGDirectory = /home/cjd/.lyricue/backgrounds
'TrayIcons = 1
'DatabaseType = mysql
'DefBible' - Default bible setting
'Bible'    - Description of bible + database name (ie. 'NIV;nivDb'), can
             be multiple
'App'      - Command-line to be run from interface on server screen, can
             be multiple
'Preset1' - Sets preset text
'Preset2' - Sets preset text
'FrameLeft'  - Size of left pane
'FrameRight' - Size of right pane
'FrameMain'  - Size of main pane


---------------
DATABASE FORMAT
---------------

Database lyricDb
----------------

# Main lyrics table, contains list of all songs and details of each
lyricMain (
  id int(11) NOT NULL auto_increment,        # Unique id of song
  title varchar(100) NOT NULL default '',    # Title of song
  songnum int(11) default '0',               # Song number from book
  book varchar(100) default '',              # Song book
  artist varchar(100) default '',            # Song artist
  written timestamp(14) NOT NULL,            # Date when song was written
  keywords text,                             # Any keywords
  entered timestamp(14) NOT NULL,            # Date when song was entered
  copyright varchar(100) default '',         # Copyright infomation
  PRIMARY KEY  (id)
)

# Lyrics of individual pages, refers to lyricMain for song details
page (
  pageid int(11) NOT NULL auto_increment,    # Unique id of page
  songid int(11) NOT NULL default '0',       # Id of song which this is page of
  pagenum int(11) NOT NULL default '0',      # Number of page in song
  pagetitle varchar(100) default '',         # Name of page
  lyrics text,                               # Lyrics contained on this page
  PRIMARY KEY  (pageid)
)

# Contents of all playlists
playlist (
  playorder int(11) NOT NULL default '0',  # Order in playlists for this item
  playlist int(11) NOT NULL default '1',   # Playlist which this is contained in
  type varchar(4) default 'song',          # Type of item. One of : 'song',
                                           # 'vers', 'play', 'imag', 'back'
  data varchar(50) NOT NULL default '',    # Dependant on type field. If:
										   # 'song' then pageid
                                           # 'vers' then verse numbers
										   # 'play' then playlist id
										   # 'imag' then image filename
										   # 'back' then background filename
  transition int(11) default '0'           # Set transition type
  PRIMARY KEY  (playorder)
)

# List of playlists
playlists (
  id int(11) NOT NULL default '0',         # Unique playlist number
                                           # If set to -1 then 'ref' contains
                                           # current page in server
  title varchar(50) NOT NULL default '',   # Title of playlist
  ref varchar(50) NOT NULL default '',     # If it's a song playlist then songid
  PRIMARY KEY  (id)
)

# Page->image associations
associations (
  id int(11) NOT NULL auto_increment,      # Unique id
  playlist int(11) NOT NULL default '0',   # playorder this item is linked to
  imagename varchar(255) NOT NULL default '', # Imageid from mediaDb
  absoluteparent int(11) NOT NULL default '0', # Top-level Playlist (enables the clearing
						# of all associations from a playlist
						# without the need to go recursive).
  PRIMARY KEY  (id)
)

# Song usage auditing
audit (
  id int(24) NOT NULL auto_increment,      # Unique id
  songid int(11) NOT NULL default '0',     # Id of song
  playdate datetime NOT NULL default '0000-00-00 00:00:00', # When it was used
  PRIMARY KEY  (id)
)

Database: bibleDb
-----------------

# Bible verses
verse (
  verseid     int(11)      not null   auto_increment, # Unique verseid
  versenum    int(11)      not null,                  # Verse number
  chapternum  int(11)      not null,                  # Chapter number
  book        varchar(30)  not null,                  # Book title
  verse       text,                                   # Verse text
  PRIMARY KEY (verseid)
)

Database: mediaDb
-----------------

# Media Database
media (
  id int(10) unsigned NOT NULL auto_increment,   # Unique media id
  category varchar(100) NOT NULL default '',     # Main category
  subcategory varchar(100) NOT NULL default '',  # Sub category
  type varchar(10) NOT NULL default '',          # [img|bg]
  format varchar(10) NOT NULL default '',        # file format
  insertedby varchar(100) NOT NULL default '',   # Who added this
  insertdate datetime NOT NULL default '0000-00-00 00:00:00', # When they did it
  description varchar(100) default '',           # Description of media
  data mediumblob,                               # The media contents
  PRIMARY KEY  (id),
  UNIQUE KEY data (data(100),description,category,subcategory,type,format)
)

----------------
CODING STANDARDS
----------------
Source tidied by perltidy -bt=2 -pt=2 -sbt=2 -anl -bbb -ce

