[Kde-announce-apps] usb_device_amaroKscript 1.3.0.0

[Kevin Bulgrien]

Name: usb_device_amaroKscript
Version: 1.3.0.0
Type: amaroK Script
Depend: 
License: GPL
More Info:
http://www.kde-apps.org/content/show.php?content=35156

Description:
 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


Changelog:
 -------------------------------------------------------------------------------
VERSION NUMBER DESCRIPTION
-------------------------------------------------------------------------------

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.

-------------------------------------------------------------------------------
CHANGELOG
-------------------------------------------------------------------------------

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
Functi
on" dialog is now titled "Configure a Plug-in?". 
The "Custom Copy Parameters" dialog title is now
"Specify plug-in parameters".  The "Select a Copy
 Tool" dialog is not 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
funct
ion.
- 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
int
erface 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 s
o 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.