usb_device_amaroKscript

This script brings generic USB media player support to amaroK because the 1.3.1 release provided with the Mandriva 2006.0 Free distribution only supports iPOD media players. The script was developed to support various hot-pluggable USB mass-storage devices that can be mounted as a file system and is only designed to support simple media players that do not require external applications to maintain special database files on the device, but simply allow playlists and media files to be copied directly to it.

The script provides the following functions:

1) USB Device | Copy music to player

Copy selected amaroK playlist tracks to the USB device. This is a simple file copy operation. The user may configure a plug-in to be used in place of the internal file copy function.

2) USB Device | Copy to player & playlist

Copy selected amaroK playlist tracks to the USB device. The script allows the user to create an m3u playlist of the copied tracks on the target. The created playlist entries can be written in a new .m3u file, or they can be appended to an existing .m3u file. This allows the user to create custom playlists without having to depend on auto-generated playlists and without having to use the player interface for playlist creation. The user may configure a plug-in to be used in place of the internal file copy function.

3) USB Device | Create a new playlist

Select media files from the USB device and create an .m3u format playlist directly on the player.

4) USB Device | Delete music & playlists

Delete media files from the USB device. This delete function masks files that it does not consider to be audio or playlist content, though the user is afforded the opportunity to identify file extensions that are allowed to be deleted.

5) USB Device | Delete music in a playlist

Delete all media files that appear in a given .m3u playlist file that is on the USB device. This function allows a user to pull logical groups of media files off of the player without requiring files to be individually selected.

6) USB Device | Purge all music & playlists

Delete all media files or playlist files from the USB device to restart loading media on an uncluttered player. This delete function masks files that it does not consider to be audio or playlist content, though the user is afforded the opportunity to identify file extensions that are allowed to be deleted.

7) USB Device | Show status & information

Report the free space on the USB device. The total space on the device is also shown. Additional statistics are planned for this dialog, but are not yet implemented.

8) USB Device | Help About

Displays a dialog that displays the version information, release date, and a copyright notice.

9) USB Device | Help

Displays a dialog that explains the function of each menu option in greater detail.

Options 1 and 2 above operate on the amaroK playlist files that are selected at the time the function is invoked. All the other USB Device functions work with files that are already on the media player rather than in the amaroK playlist. The user selects files for these function using custom file selection dialogs. This may feel odd since one must place and select files in the amaroK playlist even though those selections are not used by the USB Device menu option. This is a consequence of the fact that script functions can only be invoked with the context menu for files in the amaroK playlist.

When the script is busy processing a user-invoked command, the USB Device menu is uninstalled and replaced with a dummy menu that consists of two options that are status messages rather than function commands: 'Please wait.', and 'USB Device is busy.' Since some of the operations can take a long time to complete, this prevents the user from queueing up invalid commands, but also gives the user an opportunity to check whether the last command is still in progress or not.

USB_Device automatically handles mounting an unmounting of the media player when the user has specified the mount point. The script generally expects the mount point to be created by a hotplug event that occurs when the media player is connected to the system. It is the user's responsibility to be sure to set up any /etc/fstab entries that might be required in order to make simple mount and umount commands possible.

Even though USB_Device is capable of mounting and unmounting the player, it is also smart enough to leave the player mount alone if the user mounted it explicitly.

To use this script, install it into amaroK with the Tools | Script Manager. The "Install Script" button will properly install the tarball that contains these files.

Once the script is installed, use the "Run" button to start the script so that the context-click menus are installed and operational. All script functions are grouped under the "USB Device" context menu. This context menu appears when you right-click selected files in the amaroK playlist.

Configuration settings are stored in ~/.amarok_usb_device.

User-configurable options exist to choose the media player mount point, whether or not to use mount/umount commands, to specify a list of music file extensions that may be deleted when "Purging" the media player, and to configure a plug-in to replace the internal file copy mechanism. Yet another configuration option exists to work around issues with some systems that causes file copies to fail. Certain Linux distributions have been observed to automatically unmount the USB device when I/O is not in progress, such that the df command reports that the device has no free space because it is not mounted.

-------------------------------------------------------------------------------
REQUIREMENTS
-------------------------------------------------------------------------------

The following requirements are based on the RPM package organization in the Mandriva 2006.0 Free distribution. The script automatically checks for the presence of all requirements when it starts up.

RPM Package : Executables
============== ==========================================
kdebase-progs : kwriteconfig kreadconfig kfmclient kdialog

kdelibs-common : dcop

coreutils : basename printf df du rm sleep

mount : umount mount

mp3info : mp3info

bash : bash

findutils : find

gawk : awk

usb_device.amarokscript is versioned as follows:

x.y.z.w

x) Major release number. For this version to be incremented, a major change in the implementation or feature-set of the script must occur.

y) When a release incorporates new functionality, this portion of the version number is incremented.

z) When a release is comprised minor feature changes and/or bug fixes at the same time, this portion of the version number changes.

w) This version number is reserved for tracking new releases that are strictly bug fix releases.

1.3.0.1 Fix bug that broke things when using file and directory names that contained special characters.

Bug report by François < suske (at) brubel dot net > inspired this release.

usb_device.amarokscript.sh (bug-fix)
- url_decode() did not include uppercase alphabetic characters in the match string that was supposed to detect hexadecimal digits. This had the effect of causing certain encoded characters to remain encoded.
- transfer() dialog spelling correction.

README
- Spelling improvements.

CHANGELOG
- Spelling improvements.

1.3.0.0 Improved plug-in interface. Fixed configuration dialog title. Added workaround where copy fails when df falsely reports lack of free space on the player.

usb_device.amarokscript.sh (enhancements)
- Version information updated.
- Added "Help About" to the menu() function.
- requires() adds a missing dependency check for "sleep".
- plugins() now abbreviates the name of plug-in scripts to remove the path name so that the user dialogs are a bit more friendly.
- configure() dialogs relating to plug-in support have been modified to better fit the new, more generic plug-in interface. The "Custom Copy Function" dialog is now titled "Configure plug-in?". The "Custom Copy Parameters" dialog title is now "Specify plug-in parameters". The "Select a Copy Tool" dialog is now titled "Select a plug-in to use".
- The configure() function dialog that is used to decide whether a plug-in is to be configured now has improved user help test and is clearer about asking the user not to use a plug-in unless doing so is required to support some additional functionality that is not provided natively.
- The plug-in selection dialog in the configure() function now includes an option to not use a plug-in so the user can change his or her mind.
- The text on the configure() plug-in parameter dialog has been improved.
- A new configure() dialog has been added to support setting a new variable that allows free space checks to be bypassed when copying files to the USB
device. This is a workaround for systems that may be affected by the issue at: http://lists.gnu.org/archive/html/bug-coreutils/2005-09/msg00104.html . The df command does not work as expected on some systems because the player is unmounted unexpectedly. The value is written to the configuration file, and code to read it is also added in initialize().
- initialize() now checks more values to better detect when the configuration file does not contain all of the expected settings.
- initialize() implements an early exit to reduce the number of calls to configure().
- Various variables and configuration parameters in ~/.amarok.usb.device are renamed to better reflect the new more flexible plug-in interface. The functions configure(), initialize(), execute(), transfer() are all affected.
- execute() has been heavily modified to support calling plug-ins for various functions. New positional parameters now support this increased functionality.
- execute() no longer raises a dialog when a plug-in exits with status 0 and nothing is returned on stdout. This allows plug-ins to silently ignore an unsupported function.
- execute() now redirects the plug-in's stderr to stdout so that all of the plug-in output is displayed in the event that plug-in functions are not adequately error proofed.
- execute() now notifies the user when it invokes a plug-in by putting a notice in the amaroK status bar.
- The free() function has been moved closer to the first function that uses it.
- transfer() call to execute() now passes an additional parameter to identify the mode the plug-in call should support.
- transfer() now only checks the free space on the USB device when the user has not elected to disable free space checking.
- m3u_erase() dialog title has been improved to try to better describe that the playlist contents will determine what files are removed.
- An about() function now supports the new "Help About" command.
- The main loop adds support for the "Help About" command.

usb_device.amarokscript.sh (bug fixes)
- configure() has been modified to correct the dialog title used to choose the mount point for the USB device.

usb_device.copy.plugin
- The embedded documentation has been completely reworked to describe the new plug-in interface.
- The more flexible positional parameter interface to the plug-in is supported by a front-end processor that shows how to handle both the legacy interface for 1.2.0.0 and the new 1.3.0.0 interface. All "usb_device.amarokscript" parameters are pre-processed before doing any error handling.
- Improve description of some of the unchanged code.

README
- Updated the documentation that deals with the plug-in interface to match the new functionality.
- Added a description of the new Help About command and renumbered the list it appears in.
- Revised some of the text that describes the amaroKscript operation and use.
- Revised the paragraph that reviews the user configurable options and added a note about the new option that allows space checking to be disabled so that the script can be used even if space checking fails as observed on some systems.
- Parameter documentation has been heavily revised and duplicate content has been removed.

TODO
- Add a note about adding calls in the usb_device.amarokscript.sh code to let plug-ins take over more functions than just file copying.
- Add an idea to support writing files to a URL instead of to a mount point.
- Suggest adding the ability to avoid decoding file URLs when passing files to a plug-in.