usb_device_amaroKscript
Source (link to git-repo or to original if based on someone elses unmodified work): Add the source-code for this project on opencode.net
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
14 years ago
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.
14 years ago
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.
Support-Box
usb_device_amaroKscript is part of KDE Themes and Content, which is supported by the following people:
Other Amarok 1.x Scripts:
paulengel
12 years ago
While trying to figure out what's wrong I noticed that when I try to duplicate the kfmclient copy command I get a syntax error "Unknown command 'copy'". I tried running kfmclient --commands and it does not list a copy command. I'm not a KDE/kfmclient expert, but this sounds suspicious. I'm running kdebase 4:4.1.2-0Ubuntu4.
Any help would be greatly appreciated.
Report
paulengel
12 years ago
The fix is to edit ~/.kde/share/apps/amarok/scripts/usb_device.amarokscript/usb_device.amarokscript.sh and replace "kfmclient" with "kioclient". (The syntax for both are the same.) Now it works.
I hope someone finds this useful.
Report
kbulgrien
13 years ago
Report
kbulgrien
13 years ago
I did not want to try to figure out how to write my own udev rules even though I found a few good google references on doing just that. Instead, I found a simple way to do what I needed to do using good ole fstab. The Sansa is a vfat file system with a volume name of "TELECHIPS" as it came from the store. Here's what I did:
/dev/disk/by-label/TELECHIPS /mnt/TELECHIPS vfat noauto,defaults,dmask=5007,fmask=7117,gid=family,group,users 0 0
Then I made a mount point /mnt/TELECHIPS and chgrp'd it to a group that should have access to the media player. usb_device_amaroKscript just worked after that.
If you didn't catch it, that fstab entry is cool in that it references the volume name of the player mass storage which is automatically made into a /dev/disk/by-label/ link to the real device name. The volume name doesn't change even if the player is mounted as a different device /dev/sda1... /dev/sdb1... etc. Check out /dev/disk contents for even more choices if the volume name is not good enough.
Report
kbulgrien
13 years ago
Report
dinghds
14 years ago
I imagine this could be done with rsync, but I'd like to know in advance if it's possible at the moment.
Report
suske
14 years ago
Great job Kevin !
Finally an easy way to manage my USB/MP3 player from and within Amarok !
I'm running on SUSE10 and the following could help others:
1. You have to install the MP3INFO package which seems to be delivered with Mandriva but not with SUSE. However, the install in very easy as there seems not to have depedancies (except X11R6 ?). Thus Installing the RPM on the MP3INFO is OK (don't care it is mentionned for Red Hat, there is no dependancies problem with SUSE 10).
So, surf on http://www.ibiblio.org/mp3info/ , click the RPM file and then "Install with Yast", root password and go.
2. As SUSE automatically manages the mount/unmount of the USB-Keys, don't use the auto-mount feature of the script. No damage if you do it and the script remains working but it could bcaome difficult to know if the key is mounted or not in SUSE... Prefer to mount and unmount from Konqueror.
3. Don't use the the auto detection of the data volume on the key if the volume mentionned by SUSE is not the good one ! In this case, you'll allways have a "key full" message.
4. Follow the other recommandations of the script and just enjoy by plugging in the Key and right-clicking on the titles and lists to select the actions.
It's a first impression report, OK, but it is a very good impression ;-)
Thanks again Kevin.
Report
wipeout
14 years ago
Thanks to all the nice people that form the linux community and help spread the good word !
Report
kbulgrien
14 years ago
Report
suske
14 years ago
Great feature for Amarok in fact.
Report
kbulgrien
14 years ago
'' When a file or directory does have an accentuate character in the name, the copy won't work, I receive a message "Files selected... but not accessable...". In fact, in the path showed there after, I can see some replacement of the accentuated characters, like "é" becoming "%C3%A9". ''
kfmexec may be useful to resolve this issue.
Report
kbulgrien
14 years ago
Report
coredumped
14 years ago
But too much to fix bugs:)
I will port it on FreeBSD:)
Report
kbulgrien
14 years ago
Report
kbulgrien
14 years ago
A Help About command has been added to make it easier to see how current your version of the amaroKscript is.
Various texts that appear on the configuration dialogs have been (hopefully) improved.
For developers, the plug-in interface has been expanded to pave the way for enhanced functionality later. The sample plug-in script has code that shows how to handle the new interface without breaking backwards compatibility with the 1.2.0.0 interface.
Also for developers, plug-in output to stderr is captured and displayed in addition to the output on stdout. This should make it easier to debug plug-ins under development.
Report
kbulgrien
14 years ago
1) The configuration dialog title for the mount point dialog is mangled so it is not clear what the dialog is requesting.
2) There is evidence that coreutils 5.3.0-20.2 on SUSE 10.0 GM has a 'df' command that does not behave as the script expects. The script works ok on Mandriva 2006.0 with coreutils-5.2.1-8mdk. The bug causes usb_device.amarokscript to report that there is 0MB free on the USB device even when there is plenty of space as reported by the status command.
I have 1.3.0.0 ready for release, but I'm holding off until I get data back from the user that helped find the problem.
Report
kbulgrien
14 years ago
is a coreutils thread that shows why SUSE is affected.
Report
blujay
14 years ago
Not all of my music files are MP3s: some are Oggs already, so I need the transcoding script to handle that. But no matter what I try, the script always stops with "Error 1" when the test to see if the filename's extension is ".mp3" fails. Of course it's going to fail on an Ogg file...but that doesn't mean the script has to quit there! I want it to continue!
I've tried using grep, I've tried using case statements, and no matter what, it always kills the script before it can continue.
*sigh* I've got it working great on one filetype.
Report
kbulgrien
14 years ago
Report
kbulgrien
14 years ago
usb_device.amarokscript always passes positional parameters to the plug-in.
In version 1.2.0.0, the first parameter is the mount point, and any others are plug-in parameters defined by the plug-in author and specified by a user-configurable option.
In versions subsequent to 1.2.0.0, the usb_device.amarokscript parameters will be in the form --parameter=value. The number of parameters is not specified, but the first parameter with a value of -- will always mark the end of the usb_device.amarokscript parameters and the beginning of any plug-in parameters.
--mode=copy --mount=/mount/point -- are the new API positional parameters equivalent to the current 1.2.0.0 plug-in interface.
Report
kbulgrien
14 years ago
But, the big news for this release are the new features.
1) A status command has been added so that the user can find out how full the USB device is. Also, the number of music and playlist files is reported.
2) The script now removes the script menu when it is busy working so that there is feedback on whether or not the operation is complete. When the script is busy working, the script menu consists only of two dummy options: "Please wait." and "USB Device is busy.".
3) A plug-in interface has been added! HA! A plug-in with a plug-in interface? Yes, since people were asking for more functionality for players that needed more than file copy operations, and because interest has been expressed in having usb_device.amarokscript do file transcoding, it seemed that a plug-in interface was the best way to be able to support these things. Besides, if people contribute their plug-ins, it will be much easier for me to package up separate plug-in scripts than to hack up the main script code. A fully functional sample plug-in is supplied to make it easier for others to HACK together their own specialized copy functions for usb_device.amarokscript.
Enjoy.
Report
kbulgrien
14 years ago
Report
kbulgrien
14 years ago
The script should probably allow a user to configure it to pop up a dialog when finished.
Also, the script could replace the menu items with a "script busy" menu item (that does not do anything) so that users will not be able to cue up a bunch of commands because they think the script is finished.
More on this later. It looks like another update could produce a friendlier script.
TODO: The "Copy music to player & playlist" option should do the playlist construction using the original files and not the ones on the MP3 player so it completes more quickly.
Report
kbulgrien
14 years ago
The menu names have changed to be more understandable to your average human. I finally got around to showing my wife how to use the script, and I decided the old menu names were too geeky and didn't mean enough to her.
Also, a help command has been added that further describes what the various functions do.
1.1.0.0 removed some nice status message that told you when files were deleted because at the time I did not see a way to do it. These have been restored.
More error dialogs are now implemented to tell you what went wrong if file copy or delete operations fail.
A severe bug that crashed the script was fixed. This would occur if your amaroK collection was on a network share that was not mounted when you tried to copy files to the USB device.
Spaces in file names still weren't handled completely in the delete by playlist function. That should be fixed now.
The create playlist function dialog title was wrong as it was a copy/paste from the delete dialog so it looked like you were selecting files to delete.
A number of regressions introduced in 1.1.0.0 were corrected. These primarily had to do with improper behavior when a multi-step function was cancelled in the first step, and were directly related to the spaces-in-filenames updates. The second step should not have run in this case, but it did. For example, cancelling out of the selection of files to add to a playlist did not prevent the user from being prompted to pick a playlist file.
See the ChangeLog for greater detail.
I added an entry to the TODO as well. I'd like to see a USB Device status option so you can see what is on the player, how much free space there is, etc.
Report
DaBlade
14 years ago
Thanks :)
Report