Documentation

Music Manager User Manual (version 1.85)

NEWEST FEATURES FROM PREVIOUS VERSIONS (version 1.8)

  • Bugs detected in version 1.8 fixed.
  • Custom icons (section "changing apearence")
  • ttf fonts can be loaded from "plugins" directory (section "changing apearence")

Installation

At present, this program not need to be installed. You only need to save the "dist" folder (and possibly the "documentacion" folder) wherever you need, and execute the application from there.

Due to this, you can carry this application in an usb stick and execute it from there to manage mp3 files of any computer. However, you must remember that playlist CANNOT be copied from one computer to another. It´s not recommended save a playlist in an usb stick in order to play it in another computer, unless the playlist uses relative paths and both playlist and files are in the usb stick.

How to update the application

If you have an earlier version than 1.2, or this is the first version you download, you can ignore all this section.

You can update the application from versions 1.2 and 1.25.

If you haven´t sent any data to the server, your identifier hasn´t been generated so you don´t need to update following these steps. If this is your case, overwrite the older folder with the new one, or delete the older folder and put this one instead.

The reason to use the updater is only to keep your program identification, so you can maintain your statistics consistently.

To update properly the application, go to the folder which you downloaded this application in. Inside "dist/lib" folder you´ll find "jmmmupdater.jar" file which will perform the updating. Execute it normally (double-click in the file if you are using windows, or with the command "java -jar <path-to-file>/jmmmupdater.jar". A little window will appear to introduce some data. The data which you need to introduce are two file paths: in the above one (which is labeled "update from") put the older version, for example "/path/v1_2/dist/mp3.jar", and in the below one put the newer version, for example "/path/v1_25/dist/mp3.jar". You should use absolute paths. You can get help using the file selectors by pressing the buttons with dots. This is the easiest and recommended way. Once you have chosen the files press the "update" button.

The updating will fail if the earlier version hasn´t an identifier or the newer version already has one. The most common case is you have sent data with the version 1.2 or newer (earlier version cannot send data), and you download the latest version of this application. In this case, BEFORE execute the application you should update it.

It is highly recommended having both version in the same filesystem to avoid troubles. The updating is done by making an updated copy of the latest version in a temporary folder, and then that temporary file is renamed to overwrite the downloaded file. If those files are in different filesystem the downloaded file might not be deleted, or might be deleted but not overwritten with the created file. If this is one of these cases, an error message should appear warning you about the error and naming the created file (something like "jmmm.jar"). If this happen, you must sustitute the downloaded "mp3.jar" with this new temporary file. You should also rename the file if needed.

Please, read every message that can appear. If the update is successful, a message will confirm it, and the same will happen if the update fails.

Application execution

Depending on the OS which you are using, application can be executed several ways:

  • 1) On Windows systems (with java installed) you only double-click the "mp3.jar" file in the package. On Unix systems this effect can be obtained, but it depends on the desktop which you are using. If you need information about how to do it you can ask for that in any forum.
  • 2) From a terminal you can execute the application this way (considering you are in the "dist" folder of the provided package): $prompt> java -jar mp3.jar

There are other ways to execute the application with other results which are detailed in the "Using the command-line interface" section.

The options described below affect to the java virtual machine, but not the application. Some of these options can not be available in a specific virtual machine, if so just ignore them. This options should improve the application start-up.

  • -noverify: avoid the class verification which are used in the application
  • -Xms30m: application starts using a reserved memory space of 30 MB. This should avoid loosing time asking for memory to the OS. It is statimated that application use beetwen 20 and 30 MB although the minimum it use is about 10 MB. If you want that the application starts with another amount of memory you can change the numeric value (-Xms20m, -Xms25m, etc)
  • -Xmx40m: application use a maximum of 40 MB. You can change the numeric value like before (-Xmx50m, -Xmx60m, etc)
  • -Xmn15m:

For example you can execute the application like this: $prompt> java -noverify -Xms30m -Xmx40m -Xmn15m -jar mp3.jar

Graphic interface usage

The graphic interface has the following parts:

  1. Menubar
  2. Toolbar
  3. Song list
  4. Several info

Looking for files

The interface allows to do several types of search: normal search of mp3 files, search based on the size of the file or based on the name.

To do a normal search, there are 2 ways:

  • 1) Clicking the "search" button or in the menubar -> Tools -> add folder

    This will do a mp3 file search from the selected folder. This folder will be selected from the next window which will be shown to do the selection.

    This type of search will add the results to the previously obtained ones.

  • 2) In the menubar -> Tools -> new folder

    This will do the same action explained before, but the results will be overwritten (the results will be deleted and then the new results will be added)

There is also an advanced search, by size. Do the following:

  1. Clicking in the "size search" button or in the menubar -> Tools -> advanced search -> size search. his will show a new window to input data.
  2. Select one of the following options:
    1. "search with lower size" to look for files with lower size than the value
    2. "search with greater size" to look for files with higher size than the value
    3. "search in interval" to look for file between two sizes
  3. Input the size (or sizes, if you want to look for in an interval) in MB, and click the "search" button ("cancel" button will cancel the operation).
  4. Next steps are the same as doing a normal search adding the results to the list.

Realize that selecting the "search in interval" option will show a new field to input the second value (needed to define the interval). Not worry about input the value the other way round, if so, a message saying that the interval has been modified will appear. You can input decimal values to define the size if needed.

A new advanced search (by name) has been added. To use it, do the following: In the menu -> Tools -> advanced search -> name search. A new window will appear you to input data. Input a string and select your wished options.

  1. "search in the beginning" search coincidences between the inserted string and the beginning of the filename.
  2. "search in the end" does the same, but the coincidences are in the end of the filename. Extension is added automatically so it is unnecesary put it.
  3. "search in the middle" does the same, but the coincidences are in any part of the filename.

Realize that, for this cases, the search is case-sensitive ('s' is not equal to 'S'). If you prefer not to do this distinction, mark the "ignore case" checkbox.

For advanced users, the option "use regular expresion" allows you to search using a regular expresion. The regular expresions you can introduce are based to the java documentation provided. You should watch the "java_regexp.txt" file enclosed in the documentation, because it´s posible that the regular expresions change according others regular expresions accepted by another program.

If you think the searching is taking a long time or you mistake the searching directory or whatever, you can stop the searching by click the "parar busqueda" button. It´s a progresive stop so hold on a little longer until the program is ready again.

Additionally, a little search monitor has been added to show the search progess. It only shows the current scaning directory and the number of scanned files. The scanning isn´t necessary done following a particular order, and the number of files isn´t accurate. Both data depend on the searching method which is currently used, and it is posible that some files are being counted twice, but they are scanned only once. Monitor will appear after 3 seconds from the start of the search, if the search hasn´t finished yet. This option cannot be configured, but so in future versions.

IMPORTANT NOTE

To prevent errors, you can only do one search at the same time.

DONT use this software to do searches in the whole system. If you need to do it, you should do smaller searches to avoid possible system overloads.

Searching methods

There are currently 3 methods to look for files:

  • 1) "Multithreading2" the one which has been used
  • 2) "CachedFile"
  • 3) "Mp3Extension" added in version 1.5

Multithreading2

This method use a multithreading search through the filesystem. It only needs the "MaximumThreadPool" and "MaximumDepth" parameters, which are obtained from the configuration file. If those values don´t exist some default values are taken.

CachedFile

This method use a text-file-based search. The file must contain a list of absolute paths to files. Search is done within that file, so if a file doesn´t appear in the list, it never will be shown. Files returned from this method exists in the filesystem, ignoring those which not.

This method is faster than the other. However, an user depending file is needed (i cannot provide a default file), so this is not the default searching method. The file is fetched with the "CachedFile" key (in the configuration file), and "MaximumThreadPool" and "MaximumDepth" keys don´t have effect in this searching method, this moment at least. The value for this key should be an absolute path to avoid problems finding the file. If you have problems, use the GUI (in the menu -> Edit -> preferences), select "CachedFile" as searching method and use the file selector (click on the "..." button)

Name of this file hasn´t any restriction, so you should use a .mmlf file (which are generated by the application) as starting point. Then you can raname the file as you wish.

The application doesn´t maintain the file, so the maintenance must be done by hand: if you add new files in a folder, those files should be added to the "CachedFile" file. If not, those files won´t appear in the searches.

Mp3Extension

This method is similar to the CachedFile method, whereas the cache-file maintenance is automatic. The file is always the "extensionCache" within the application folder. This file is used to speed up the searches, and can be deleted if you want to, but keep in mind a new file will be created whenever you use this search method.

To avoid troubles in the cache file, the file is updated whenever a search ends successfully (if you cancel the search, the file won´t be updated).

This method always uses the "mp3Extension" key (in the configuration file) whether the key is activate or not.

Introducing files by yourself

If you want to add individual files do the following: In the menu -> Tools -> add files. You will be provided with a window similar to the searchs, but now you can select the mp3 files you want of the directory you want. Realize that if you want to add files of several folders you may need to do this several times.

Playing files

If you want to play files you can do the following: Select the files you want to play from the list. You can select several files using the common way (Ctrl + click or Mayus + click). When you have selected the files, select the player that you want to use (left from the file list). That will be the player which will play the files. When you are done, click the "play" button. Maybe the reproduction takes a little longer.

Obviously, you must have installed the player you want to use, if not, an error will appear. Additionally, it´s posible that even having installed the player, an error saying that the executable couldn´t be found may appear. This is due to the player is supposed to be installed in the SO default folder ("c:\Program files\..." for windows and "/usr/bin/..." for linux). In this case, this application acts as if you don´t have them installed, so you cannot play the files.

Keep in mind that clicking the play button in this application the selected files will be modified to add one to the play count of that file. In order to monitorize the time spent in this task (it can take a bit long, depending on the number of files) a window will appear to show the task progress. Even if the window is closed, the task will keep on. This action won´t delay the player launching.

Openning and saving lists

To save a playlist made with this application go to menu -> File -> save list. A window to save the file where you want with the filename you want will appear. Regardless of the filename, the file is saved with .mmlf extension (which is the own program extension) or with the selected extension. The files which will be saved are all of the list, regardless if they are or not selected.

To open a playlist (a previously saved .mmlf file) go to menu -> File -> open list. A window will appear to select a file. You only have to search the .mmlf file you want (or the file with the selected extension) and open it.

If you don´t plan to create a reproducible playlist in a player, you should open and save .mmlfc files because their size is lower. .m3u and .pls files are playlist files recognized by a lot of players and can be opened with them. The .mmlf format is conserved because of compatibility of previous versions of this application.

In this instructions, an .mmlf file has been supposed to be used, but this instructions can be applied with all suported formats (.mmlfc, .m3u, .pls)

IMPORTANT NOTE

Both at the opening and saving a playlist, this program check the existence of the mp3 files. If any mp3 not exists, it will be ignored without warn (it makes no sense to show files which not exist). If you open a list which contain nonexistent files and you don´t save it, those files will still be in the list. This isn´t a big problem, but in some cases the .mmlf file containing the list can take a lot of space which it shouldn´t.

Relative path support allows the application write relative paths in all types of supported files. The reading of the files is done automatically, so you don´t realize whether the file contains relative paths or not (in any case, files will be displayed with absolute paths). However, when you write the file you will be asked about whether you want to write using absolute paths or not.

This option is useful in usb devices, so it is recommended if you want to write a playlist with all the files in that usb.

What is the difference between using absolute or relative paths?. A file with absolute paths can be moved to any location of the filesystem (whenever the mp3 files don´t move). However, it is usually impossible move the playlist from one computer to another, even in a usb device, because the file content knows the whole filesystem from the root folder. Using relative paths, content knows a part of the filesystem, associating the mp3 files from the playlist file, not from the root folder. This make the file moveable with the mp3 files like they are a package.

How use this support?. Move the mp3 file in a usb device. Next make a playlist file of those mp3 files with this program (using relative paths) and save it in the usb (usually in the root folder of the device, so you can easily use it). Taking advantage of the non-installation of this program, you can put this program in the usb device. Remove the usb from de computer and insert it in another computer. Playlist of the usb (if you have used relative paths) will be recognized by this program and by others who support that file format.

Tag editor (v1)

This application provides a simple ID3v1 tag editor. Despite the file haven´t that tag version (maybe it have ID3v2 tag version), you can use this simple editor.

To use it, select a file and go to Tools -> editorv1. To edit the tags you must only fill the fields and click the "accept" button. You can leave some fields blank or remove them. The unique obligatory field is the "genre" field. Changes will be written only by clicking the "accept" button, and not other, so if you make a mistake you can cancel the operation.

The following restrictions are applied (from ID3v1):

  • The "author" field must have a maximum of 30 characters. The remaining characters will be ignored. The same is for the "title" and "album" fields.
  • The "year" field must have a maximum of 4 characters (the corresponding year) Same as before, the remaining characters will be ignored. No checks will be performed, so (at your own risk of looking stupid) you can input non-numeric characters in that field.

Tag editor (v2)

As well as the tag editor v1, this one allows you to modify data related to the author, title, etc, but using ID3v2 tags. Currently, ID3v1 and ID3v2 tags cannot be "synchronized" automatically, so you have to do it manually if you want to.

ID3v2 allows you to "define" artworks within the mp3 file. This editor can manipulate those artworks so you can add, delete or sort the artworks. Other programs often show the first artwork found, so you can sort them at will to force programs to show the specific image.

Version 1.7 adds playcount and popularimeter support. These tags are rarely used. Popularimeter is usually saved by other applications in another place, and the playcount is usually ignored. That´s why it´s possible that the playcount and the popularimeter are both 0

Playcount cannot be modified for now. It will only be incremented when the user click the play button OF THIS APPLICATION. Other applications (typically players) don´t usually modify this value

About file popularity, this application saves the value within the mp3 file. Some other applications might be able to read the value, but this is not common

Anyway, all information is saved within the mp3 file, so if you send the files through Internet, that information will be there.

Changing appearance

A feature to change a application appearance is included by plugin usage.

To change the appearance, having "java Look and Feel" known packages is needed. You can download some of these in "http://www.javatoo.com/index.html" or in someother sites. Generally, these packages are distributed in a .jar format, and you only need put them in the "plugins" folder within "Music Manager". This application does some basic checks, and loads the classes which could be used as Look and Feel. Some of these packages can have some special characteristics, so generally you will need check the documentation provided by the package´s developer.

Once the application is started, click the "lightning" button in the toolbar. A window with the themes that can be applied will appear. To use one of them, double-click the one you wish to load; if everything is OK, the appearance will change according the loaded theme. You must realize it´s possible that, between all listed themes in that window, only some of them could be loaded.

Additionally, a plugin called "TinyLaF" is included, with his own documentation. To know how to use it, check the "TinyLaFdoc.txt" (or "TinyLaFdoc_en.txt") file or check the documentation provided by de developer.

From version 1.25 you can custom a bit more the application adding custom backgrounds to the application. Suppose you have an image you want to put as backgrounds called "bg1.png". Put this image into the application "plugins" folder, and rename the image as "layered.png". In this case the image will be shown as the background of the whole application. The same way, if you want to put additional backgrounds to the left side, where the information about the mp3 file is shown, and/or right side, where the file list is shown, copy other files to the same location and rename them as "scrollbg1.png" and "scrollbg2.png".

Images can be in .png, .gif or .jpg format (with those extensions) and will be checked in that order, so if a "layered.png" image exists, that image will be loaded but not "layered.gif" or "layered.jpg". Gif animations are supported, but they aren´t recommended due to the heavy resources usage what can be needed. Animated gifs bigger than 20MB can be troublesome, so static images are prefered.

The background image (layered.png) can be scaled depending on the configuration file ("ScaleBackground" key) but the other images will always be scaled.

If some image doesn´t exists, then it will be ignored.

From version 1.85 you can customize the application icons. It isn´t required an icon pack for the application, but it´s recommended to avoid showing warning in the log. If some icon is missing a default one will be shown. The default icons are those who had been shown in previous versions.

In order to use an icon set, create an "icons" folder in the application directory (that directory would contain that folder, the "plugins" folder if exists, the "mp3.jar" file, the "config.conf" file, etc). Inside "icons" folder create another directory with any name (for example, "icons1") and inside this place your icons. The application will recognize those icons as the "icons1" icon set. Go to menu -> preferences -> themes and inside "icon set" should appear the name "icons1". Select and save.

Each icon set should contain the following files (with extensions .png, .gif or .jpg): "add", "arrow_down", "arrow_undo", "arrow_up", "bin", "book_open", "cancel", "computer_link", "control_play", "file", "find", "folder_explore", "lightning" y "stop". Other files will be ignored.

You can also change the font used by the application. Previous versions allowed you to change the font to some other font installed in the OS. Now you can use non-installed fonts, but they must be in ttf format. Just put the .ttf file in the "plugins" directory.

The application selects the fonts installed in your OS by its family name, but it selects the font inside the "plugins" directory by the file name.

The selected font is tried to be shown except you´re using the GTK look&feel (also known as "system specific" in linux, because in windows another look & feel is used)

Drag and Drop

The drag and drop support is only available on the mp3 file list. Starting from a file browser like the windows one, you can drag a file or a file list and "drop" into the mp3 file list, like other programs can do it. Files will be added to the list in the position you drop them, without reorganizing the list.

In the same way you can drag and drop from the file browser to this application, you can do it on the contrary. Actually you can do it between programs which work with files. If we focus on the interaction between file browser and jmusicmanager, if you drag and drop from the file browser to jmusicmanager, you will add that file to the mp3 file list. If you do on the contrary (from jmusicmanager to the file browser) typically, because it depends on the browser you are using, you will move the file from his original location to the new one. If you keep typing the "shift" key while you are doing the drag and drop, you will copy the file to the new location.

If you are using Windows, you must realize you cannot move files with this method. You can "import" them but not move them using drag and drop from jmusicmanager to the file browser, but you can copy them.

Moreover, this new feature allows you to reorganize the mp3 file list in an easier way, only by selecting them and dragging to the new position in the list. If you want to duplicate those files in the list, you can do it by keeping typing the "shift" key at the same time you drag the selected files to the new position. This can be useful in some cases.

Take into account the following considerations:

  • Moving the file implies the file will be deleted from the list. If you move the file to another position in the list, the file will be deleted from the old position and added to the new one. If you do a drag and drop from the list to a file browser, the file will be deleted unless you are copying it. In this case, windows file browser will show an error denying the file movement, but the files will be deleted from the list anyway.
  • There is a little bug when you want to move a file to his inmediately upper position: no movement is done. You can move it using the keys "+" and "-", or move the upper file down.

Additional options

To delete files from the current list there are 2 ways:

  • If you want to delete some files, select the files you want to delete from list and press key "supr".
  • If you want to delete all files from list (like doing a "new" in other programs), additionally to the first way, you can go to menu -> Edit -> delete all. In this case, it´s no necessary to select any file.

To select files from the current list there are 2 ways (as same as before):

  • To select some files clicking the file is enough. "Ctrl + click" or "Mayus + click" to select more than one file. This is the standard behaviour of a multiple selection list.
  • To select all files, additionally to the first method, you can go to menu -> Edit -> select all.

If you make a mistake adding or deleting files (including opening a playlist) you can undo the action going to menu -> Edit -> undo.

It´s provided a method to do searchs with a random result. To activate it, go to menu -> Tools -> randomize. A random subset of the result of the search you are going to do will be selected. For example, if you do a size search with size less than 4MB and randomize the result, every files that will appear will have a size less than 4MB, although there are more files having that feature. This option only affects at searches, without including both the file addition by yourself and the loading of files (mmlfc files).

Another option you have is mixing the result. Go to menu -> Edit -> shuffle. This will mix the list contents, and you can save the list mixed up if you want. It is important doing this at the last moment, because another modification in the list will sort herself.

You can also manipulate the list rising or falling the file positions previously selected. To do that, select the files you want to modify its positions, press the key "+" if you want to rise or "-" if you want to fall. The same said in the previous paragraph is applied here: doing any modification in the list will sort herself.

From version 1.25 a couple of new options have been added to remove duplicated files:

  • The option "Remove duplicates" every duplicated file will be removed. The list must be sorted because if this isn´t the case some duplicated files might not be removed. This method consider a file is duplicated if the file absolute path appears more than once. For example, files "/tmp/abc.mp3" and "/tmp/abc.mp3" are the same file so one of them would be removed (it removed the second file), but the file "/otro/abc.mp3" wouldn´t be considered as duplicated by this method. Applying this method in the list "/tmp/abc.mp3", "/tmp/abc.mp3", "/otro/abc.mp3" will result in the list "/tmp/abc.mp3", "/otro/abc.mp3"
  • The option "Remove duplicates 2" has the same purpose, but it do it in a different way. In this case, the list don´t need to be sorted. This option consider a file duplicated when his name is duplicated in the list (the path doesn´t need to be the same). The removed file is the second which appears. Continuing with the example before, applying the method to the list "/tmp/abc.mp3", "/tmp/abc.mp3", "/otro/abc.mp3" will give you the result "/tmp/abc.mp3" only.

Be careful with the throughput of both methods: first one ("Remove duplicates") is faster than the second one ("Remove duplicates 2"). Moreover, the application will be blocked until these method has finished their task, so you won´t be able to do anything until then. Particularly, "Remove duplicates 2" method has been tested with a list of about 1700 items with few duplicated items, and with another list of about 3500 items and about a half of them duplicated. In both cases, although noticeable, the block effect is aceptable (about 1 second)

You can also sort the list based on a criteria. To do so, in the menubar -> Edit -> order by, posible options will be shown up there. It is recommended to use the key "mp3Extension" in some of those options when you add the results. If not, it is posible to have a bad throughput and the application will be frozen until the sort is finished.

Version 1.8 allows you to reload the information stored in the "extensionCache" file. This is particularly useful if you manipulate mp3 files with other applications because you can resynchronize the stored information and provide coherent results. To use this option, simply select the files whose information you want to reload and go to menu -> Tools -> reload file information.

Additional information

The interface provides additional information about several things:

Above the player selector there is information about the list. The information about the size in bytes and the number of files is updated whenever the list changes (both inserting, deleting and undoing). However, the time is only updated by doing a search (it´s no sense on other circumstances)

The duration of the list is shown only if all files in the list have been added using the mp3Extension feature. If you ́re not sure, clear the list, activate the mp3Extension feature in the configuration and add the files again

Below the player selector there is information about the selected file in the list. If more than one file is selected, the information about the first one will be shown, ignoring the rest. Realize that the information about the file is obtained from the tags of the file, and they maybe don´t be available, maybe be uncompleted, or maybe are wrong.

It is shown the following information: song author, song title, album, release year, genre. To interpret the genre field there are tables on the web (try to search about id3v1, id3v2, tag mp3...)

Information about the bitrate and the song duration has been added. This info is not related with the tags, so it is possible that the file hasn´t tags but this information appears.

The first artwork is also shown below this information.

Hotkeys

  • Ctrl + o -> open playlist
  • Ctrl + s -> save playlist
  • Ctrl + q -> quit
  • Ctrl + z -> undo
  • Ctrl + a -> select all
  • Ctrl + supr -> delete entire list
  • Ctrl + u -> delete duplicates
  • Ctrl + Mayus + u -> delete duplicates 2
  • Ctrl + Alt + p -> preferences
  • Alt + r -> play
  • Alt + b -> search
  • Alt + p -> stop search

Using the command-line interface

To execute the application from the command-line execute the following:

java -jar <path to executable>mp3.jar <options> <files>

where <path to executable> is the folder in which you have the mp3.jar file (which is our executable). For example:

(windows) java -jar c:\mis programas\dist\mp3.jar (linux) java -jar /home/user1/bin/dist/mp3.jar

This application supports the following options:

1) --help
shows help.
2) --disable-gui
disable the graphical interface. This is important if you don´t want the graphical interface to appear. (see explanations)
3) --input <file>
open the "file" file (must be a file with a supported format) and shows the contents.
4) --find <folder>
do a normal search showing all found files from the specified folder
5) --output <file>
save the found files into the "file" file
6) --randomize
randomize the search result (maybe done with --find) but not the search part come from --input
7) --shuffle
shuffle the result. Includes both the --input part and the --find part
8) --findt <folder> <t1> <t2>
does a size search from the selected folder with a size interval between t1 and t2. See the xiii explanation for more info.
9) --find-regexp <folder> <regexp>
does a name search from the selected folder. The search is done based on the given regular expression.
10) --relative
save the mp3 file paths as relative paths. This option only works with the "--output <file>" option. If this additional option doesn´t appear --relative will be ignored.
11) --server
starts the application in server mode. This is a priority option after --help option

The "working method" of the application is the following:

  • Open the input file, adding its contents to the list
  • Do the search, randomizing the result if you want, and adding the results to the list
  • Save or show that list

DETAILS

  • i) "--help" option has the highest priority, so if it is present the rest of the options are ignored, showing only the help.
  • ii) "--disable-gui" option is necessary if you want to disable the gui. If the gui is not disable with this option the rest of the options will be ignored and the specific files will open with the gui. In this case, the files which are not ".mmlf" (or other supported format) will be ignored without warn, and if the ".mmlf" file not exists then it will be notified with an error window before open the gui.
  • iii) if the "--disable-gui" option appears, the "files" part of the command line will be ignored (even if the file exists)
  • iv) "--input <file>" option open .mmlf files (or other supported format). if the specific file isn´t a .mmlf file an error message appears (but the application doesn´t stop itself). If the file not exists (being an .mmlf file) an error message will be showed the same way.
  • v) "--find <folder>" option works as the same way as the "--input" option as for as messages shown.
  • vi) "--output <file>" option save the info with the specific format. The file must have a supported extension.
  • vii) Duplicated options will be ignored. Only the first option will be borne in mind. For example: the command "java -jar mp3.jar --input ar1.mmlf --input ar2.mmlf" will have the same effect as "java -jar mp3.jar --input ar1.mmlf"
  • viii) If you specify more than one file with the "--input", "--find" or "--output" option only the first file will be borne in mind, ignoring the rest. For example, the command "java -jar mp3.jar --find dir1 dir2" will have the same effect as "java -jar mp3.jar --find dir1"
  • ix) option ordenation doesn´t mind
  • x) the output of the result depends on the "--output" option. If it´s present, results will be redirected to the specific file, if not results goes to the standard output.
  • xi) "--randomize" option only make sense with the "--find" option. This doesn´t implies an error or warn appears if the options don´t appear together; it only hasn´t an useful effect.
  • xii) "--shuffle" option can be applied both with the "--input" option and the "--find" option. The disorder is (theoretically) at random, so you can execute the same program several times and have a different result.
  • xiii) "--findt" option allows to do search based on an interval of file size in MB. It´s also possible to do search based on a size lower or upper than one specified. To do a search with a file size lower than one specified putting a right interval is enough (--findt dir 0 3); but to a search with a size upper than one specified you must put something like this: "--findt dir 4 0". It is important that the interval upper bound is 0 or a negative number, otherwise the result will be other than expected.
  • xiv) "--find-regexp" option does a file name search based on a regular expression. It´s advisable quoting the expression to avoid possible shell interpretations. Realize that the expressions are accepted based on the provided java api, so check the "java_regexp.txt" file enclosed, which is a extract of that api, to put the accepted regular expressions.
  • xv) It´s possible to put the "--find", "--findt" and "--find-regexp" options together. The searchs are done separately, providing a unique result, which is the set of all files found. Repeated files may appear if the file is in the result provided by one or more searches.

Socket interface usage and server mode

Socket interface is ALWAYS available if you are using the server mode, and in a configurable way (you can activate or not) using the GUI

Socket interface allows you to manipulate the application through a port. The default port is 10001 (which should be free) but you can change it in the configuration file if you wish. Through that port the interface receives commands to be able to manipulate the application.

To activate this interface along with the GUI, you can put the key "DisableSocketCommand" with the value "false" in the configuration file, or from the GUI, in the menu -> preferences -> Misc tab -> unckeck the option. Additionally you can select the port where this service will be listening. Put the key "ListenPort" with the corresponding value, or like before, from the GUI. It is recommended these options be fixed before executing the application, from the configuration file. Changing these options from the GUI will cause all opened connections will be closed to restart the service in the new port or to stop the service.

Allowed commands are, for now (without ""):

  • "/search <dir>": it does a search from that directory. This search adds the results to whatever results searched before. The directory name goes from the character just after the space to the end of line. It is not necessary quote the directory name (quoting it can cause failures). For example: ->/search /my/searching dir/number1 (it will search in "/my/searching dir/number1")
  • "/getNumberResults": returns the number of results found
  • "/clearSearch": remove all results to start a new search
  • "/getSearchResults all": return all results found (one filename per line)
  • "/getSearchResults <lowerBound> <upperBound>": returns results between <lowerBound> and <upperBound>. These values must be between 0 and the number of results - 1
  • "/removeSearch all": remove all results. This command does the same as "/clearSearch" command
  • "/removeSearch <lowerBound> <upperBound>": remove results between <lowerBound> and <upperBound>. The rest of the results are shifted to fill the removed files
  • "/saveAbs <file>" save results in the specified file using absolute paths. The filename must have a supported extension. You should not quote the filename, which goes from the character just after the space to the end of line. For example: ->/saveAbs /my/results dir/number1/r1.m3u (it will put the results in the file /my/results dir/number1/r1.m3u)
  • "/saveRel <file>": the same as the command before, but save the results using relative paths.
  • "/help": shows the help
  • "/exit": closes the program
  • "/close": close the connection (the program keep running and it can listen other connections)

All these commands will be reflected in the GUI if you are using the GUI

To execute the application in server mode, start the application with the "--server" option. For example:

$prompt> java -jar mp3.jar --server

In this mode the application is manipulated through sockets, without the GUI. You can comunicate with the application through a telnet connection, or using another application which can comunicate with this.

The configuration file

The configuration file ("config.conf") is a file which can be edited by hand to configure the application. The provided conf file is valid, and before modify it you should copy it.

The conf file is made using key-value pairs, so the key must be unique. Details about keys that can be used will be shown now, with his respective possible values. It is important to write case-sensitive, otherway it is highly possible that the key or the value will not be recognized.

This file is only read once at application startup. Changing this file during application execution won´t have inmediate effects

If the conf file doesn´t exists, some default values will be taken.

The GUI offers an easy way of changing the configuration file. If this file doesn´t exists a new file will be created with the selected values. Options which have been changed this way will have inmediate effect unless the contrary is specified.

Keys with values

  • "LookAndFeel": The default look and feel which the application will take. The default value is "system specific", which is the one that is used by the system. To change it, you must put the name of one of the available themes in your system. When you change the appearance (see "changing appearance" section), you should see a list with the available theme names. You must write one of them as a value of this key, being case-sensitive. If the written theme doesn´t exists, or there is some kind of problem (like the theme cannot be loaded), the "cross platform" theme will be put instead, so this should work. Generally, the value for this key is a class name within the system, for example "com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel", however there are two exceptions: values "System Specific" (OS specific theme) and "Cross Platform" (default theme).
  • "MaximumThreadPool": maximum number of threads what will be used searching files, both interactive search and using command-line. You must put a positive integer value greater than 0. You must realize that a too much high value can have an important effect on the system performance, and can stop the system. If you have a doubt, keep the default value (4) which should have a good performance. This key is used by the "Multithreading2" searching method.
  • "MaximumDepth": maximum depth of the search. The search will not continue looking for files when that depth has been exceed. The depth is measured from the initial folder forward. For example, a value "1" indicate that the search will look for files in the initial folder and subfolders of the initial folder; a value "0" only look for files in the initial folder; a negative value will block searches. You should adjust the value to your own necessities, and a too much high value can provoke troubles because of the high number of folders that the application must search in. The default value should be enough for a lot of occasions. This key is used by the "Multithreading2" searching method.
  • "NoAutoCheckUpdates": indicate if the application should check for updates. A value "true" blocks the check, and a value "false" allows it.
  • "playerXXXX": the key might not be the same as this, if the key starts with "player" is enough. You can write "player1", "player2", etc. The value of this key must be a path to a mp3 player. The value of these keys will appear in the player selector, and it can be used to play the files. You should bear in mind the following.
    • The existence of the file is NOT checked. It is recommended to use absolute paths. Trying to play files with a non existing player will produce an error.
    • The executable MUST be able to execute as "<executable> <files>". If not, the application tries to execute and it is possible nothing appears, either a notification. If your player cannot be execute this way, you should do a script to call the player this way. The same occurs if you need to put options. If you have trouble with a player, you can contact me and i try to provide you the script.
    • This application acts as a player launcher, so it is recommendable the player can be easily manipulated. Once the player is launched, the application doesn´t control it, so it can be difficult launch a player which cannot be controlled. That´s why you should launch a player which has a graphical interface.
    • 4) FOR WINDOWS USERS: As the windows paths use the "\" character you must duplicate this character so the path is well interpreted. For example: player1=c:\\Program files\\players\\mine.exe or player2=d:\\my portable player\\good\\portable.exe
  • "Language": change the current language to another. Possible values are:
    • 1) "default" for autodetect de system language and try to select the proper translation
    • 2) "en" for change to English language
    • 3) "es" for change to Spanish language
    Change the value to another out of those will set the language to English. If you set the language to "default" but your language is not one of those the language will be set to English. Changes will be shown by restarting the application.
  • "SearchingMethod": use a specific searching method. Posible values are: "Multithreading2", "CachedFile" and "Mp3Extension". Check "Searching methods" section for more info.
  • "CacheFile": This key is only used if selected searching method is "CachedFile". For example: SearchingMethod=CachedFile CacheFile=/path/to/cache/file It is recomended use absolute paths to set the cache file, although it can work with relative paths. To do this, set a relative path from your working directory. Your working directory is shown executing the application from the terminal, and generally (executing the application from the jar file) should be the "dist" folder where the application is.
  • "DisableSocketCommand": Disable the socket interface. This key is only used if you are using the GUI, but it is ignored in server mode. Enable or disable this key allows you to open (or close) the corresponding port to listen commands. Changes are applied immediately: if you disable this option (the value for this key is "true"), all active connections will be closed.
  • "ListenPort": listen port for the socketCommand. This key is used if the application starts in server mode (regardless of the "DisableSocketCommand" key state), or if the application starts in graphic mode (GUI) and the value of the "DisableSocketCommand" key is "false". Changing the port value implies restarting the socket service in the new port, so the opened connections in the old port will be closed.
  • "NoSendReports": it indicates of you want to send information to the server. The information is sent when exiting.
  • "ScaleBackground": it indicates if the background (if any) should be scaled or not
  • "FontName","FontSize" y "FontStyle": name, size and style of the font which will be used in the application. Posible values of "FontStyle" are "Plain", "Bold", "Italic" or "Italic Bold". Values for "FontName" are whatever name font installed in your system. The chosen font will be used in the entire application but error message. Using a weird font can leave the application in a bad state. If this happens, edit the configuration file and delete the entries for "FontName", "FontSize" and "FontStyle".
  • · "UseMp3Extension": If you use "Multithreading2" or "CachedFile" searching methods, this key indicates whether you want to store additional information about mp3 during the execution of the application or not. "Mp3Extension" searching method always use this key even having this key desactivated. Having this key activated will slow down the searches, but the manipulation of the list files will be speed up. If you want to sort by time the list, it is recommended to have this key activated, so the sorting will be almost immediate. If you don´t have activated this key, the sorting will last longer and the application will be frozen until the action finish. This is a "severe" case to use this key. If you want to obtain the file information, this key is recommended, even though the usage is not always so critical.
  • · "IconSet": The icon set you want to use. It should be "default" to use the default icon set or a name of a folder inside "icons" folder within the application directory.

Reporter

From version 1.2 exists the option to send application usage information in an anonymous and transparent way. You just need to enable the reports sending in the application configuration. This option will be enabled by default. If you want to disable this feature, just go to the configuration file and find (or add if the key doesn´t exists) the key "NoSendReports" and put the value "true". You can also do it from the GUI: In the menu -> preferences -> Misc -> check the option to not send reports.

What information is sent to the server?
An unique identifier which will be generated in an automatic and transparent way, the application version, the last time you have executed the program, the number of times you have executed the program, the number of times you have executed in each mode (command-line, GUI, server) and more application-related information.

This information is sent to the server to be processed.

For now you can only send data, but you cannot retrieve that data. Future version are going to extract the information from the server, so you can make some kind of statistic with that information.

To create your identifier it is necessary overwrite the executable. This is done in a completely transparent way in linux, but no so in windows.

Plugins

Plugins are stored inside "plugins" folder. Plugins packages contains one or more .jar files which should be moved to that folder. It´s developer´s responsability providing the .jar files needed for the plugin to work correctly.

Some plugins may use libraries which are already stored inside "plugins" folder by other plugins. It is recommended to use the newest library and remove the older one. Having the same library twice isn´t good.

You can access to the plugins from menu -> plugins (initially empty if no plugins are detected). Some plugins may need to be configured, or may require to do some previous actions (select files from the list, for example). Read the instructions before using it.

Plugins who have not been tested for a specific version of this application will appear with "!?" in the menu. This doesn´t mean that the plugin won´t work, but it´s possible that the plugin fails because it hasn´t been tested. You can access to the plugin anyway.

Version 1.8 adds a new type of plugin to manipulate the list of files. This plugin causes troubles with earlier versions of this application hindering the execution of this application. If you have this issue, update the application or delete the plugin

Plugins developed for version 1.7 should work well with newest versions.

Log file

The application log file "jmmm.log" can provide useful information both user and developer. If something doesn´t work as expected check this file, and no doubt about send it to me to be able to solve the problem or to explain how you can solve it.

The file will be overwritten every time you execute the application so you can rename it if you want to keep it. You can also delete it, but a new one will be created next time the application is executed.

Interesting notes

How convert formats easily? Execute java -jar mp3.jar --input formato1.mmlf --output formato2.m3u --disable-gui You can convert the playlist from a format to other (if the format is supported)

How generate varied playlist? Execute java -jar mp3.jar --disable-gui --randomize --shuffle --find <dir> --output list.m3u The list.m3u playlist will change its contents every execution of this command You can put it in a script with a command to execute a player which supports m3u playlist to have varied music whenever you want (for example, at the start of our session, or with a simple click)

Small bash script (Unix) to copy a mp3 list to a location: $prompt> java -jar mp3.jar --disable-gui --input $list_location --output /tmp/jmmm_output1.mmlf ; while read line ; do cp "$line" $target_folder ; done < /tmp/jmmm_output1.mmlf where $list_location is the path to the list (in one of the supported formats) and $targer_folder is the the folder where the files will be put inside.