
irmp3 browser module shell script execution
===========================================

This directory contains sample shell scripts you can execute from irmp3 
its browser module.


Execution pre conditions
========================

A shell script can be executed in the following cases:

1. Shell script is called when browsing files and using the "browser add"
   or "browser play" command

    - config file option 'browser_exec' must be set to a valid subdirectory
      of 'browser_root'
    - config file option 'browser_mask_exec' must be set to your desired shell
      script extension (default is '*.[Ss][Hh]')
    - shell script is located below the path "browser_root/browser_exec"

2. Shell script is directly called using the "browser exec <filename>" command

    - no special conditions required: any shell script will be executed
      

Shell script arguments
======================

NO user specific script arguments can be passed!

When executing a shell script this script will get 4 internal parameters:


Paramter	Meaning
Number
--------	------------------------------------------------------------

    $1		Temporary file where the script can leave a one-line-message
		that will be displayed on your irmp3 lcd after execution.

    $2		Current browser directory

    $3		Current browser cursor
    
    $4		Current cursor's file type:

		    dir		= directory
		    audio	= audio/mp3 file
		    list	= playlist
		    listlist	= playlist-list
		    exec	= executable shell script
		    other	= any other file

Message passing
===============

There are two possibilities to display output produced by a shell script

1. short and easy

    A shell script can leave a single line message that will be displayed 
    for a short time on irmp3 its lcd display.
    The file where this information must be written to is set by irmp3 config
    file option 'browser_execmsg' and is passed to the shell script as 1st
    command line parameter.
    Using this feature a shell script can output information this way:
    
	echo "Command successful" > "$1"

    If no output is desired, simply dont write to this file.

    If you want to disable message passing, leave config file option 
    "browser_execmsg" blank.
    
2. more complex

    Connect to lcdd, create a new screen, show information, wait, delete screen
    

Sending commands from script to irmp3
=====================================

There are two possibilities to send commands to irmp3

1. short and easy

    You can use the previously mentioned temporary message passing file, set
    by config file option "browser_execmsg". See documentation about "message
    passing" above.
    Scripts can write this message file and irmp3 will check its content:
    First line will be displayed on lcd.
    All following lines (2nd, 3rd...) will be treat as normal command to irmp3.
    Using this feature you are able to send multiple commands to irmp3
    w/o using network interface.
    See scripts/command.sh for example.

    If you want to disable message passing, leave config file option 
    "browser_execmsg" blank.

2. more complex

    Using irmp3 its mod_netctl connect to irmp3 its port and send commands
    via network interface
