YaMLib - User's Manual

Chapter 1: Introduction
Chapter 2: Before the start Chapter 3: The program
Chapter 4: Functions in detail
Chapter 5: About YaMLib  
Chapter 6: Questions and answers

zurück zum Anfang Chapter 1: Introduction

zurück zum Anfang What is YaMLib?
YaMLib - Yet another Media Library - is a program serving to manage and play back different multimedia format files (mp3, ogg, wav). The management of the given media data is prior to the program, which thus shall provide comfort and overview to the user in many respects; thanks to an intelligent media library- and playlist-system, YaMLib offers a great deal of functions that take care of exactly these tasks.
To make the creation of playlists worthwhile, YaMLib simultaneously is an easy to apply play back program. Two powerful programs merged to one, THAT is YaMLib!
zurück zum Anfang Why just another program of this kind?
In the worldwide web as well as in store there are huge amounts of offers for all kinds of play back programs and media managers; so why another program of this kind?
Well, YaMLib is different. YaMLib combines the functionality of an archive and a playing device in a single easy to use system which in addition (due to the Java Virtual Machine) runs independent from the user's operating system. Thus YaMLib tunes on to a rather revolutionary concept; that really leaves nothing to be desired, doesn't it?
zurück zum Anfang About this manual
This document is supposed to help learning and understanding the handling of YaMLib. It is to provide a clear overview as well as comprehensible explanations of the different functions of the program, and in this respect it is supposed to be a concise reference book. Navigation within this document is made possible through links from the table of contents to the individual topics and through the return arrows zurück zum Anfang that can be found next to any topic headline. The latter lead back to the top of this document (and with that to the overview) via mouse click.

zurück zum Anfang Chapter 2: Before the start

This chapter reveals how to prepare a user's computer to be able to execute YaMLib.

zurück zum Anfang System requirements
YaMLib has been coded in Java and thus functions independent from the present operating system. That means, it can be executed in any environment, in which the Java Virtual Machine (JVM) functions. The minimum of the JVM required to run YaMLib without any trouble is version 1.4.2. If this version (or a newer one) is not available on the system, it can be downloaded from the following source: http://www.java.com/en/download/manual.jsp
Regarding the hardware, there are no known limitations, while for a play back program a sound card (or integrated sound chip) should surely exist. In addition, several of the program functions depend on the efficiency of the processor as well as on the size of the available memory, so there's no actual guarantee, that YaMLib can be processed on any given system without loss in performance or functionality.
zurück zum Anfang Setting up the program
At first, the program is packed in a zip-archive file that can be opened and unpacked with any current unzip tool. The zip file contains a file with the extension .jar in which the program itself is stored. After extracting that jar-file (and several other needed files) into a user-selected directory, it's waiting there to be executed for the first time. In addition to the mentioned archive there's another file in the directory which is supposed to simplify the program start-up. Depending on the present operating system this is a batch file (e.g. in DOS/Windows environments bearing the extension .bat) with whose execution YaMLib will be started in a proper manner.

zurück zum Anfang Chapter 3: The program

This section describes some basic steps that are supposed to show briefly the functions and handling of the program. A more detailed description can be found in the following chapter.

zurück zum Anfang The first start
With the aid of the provided batch file, YaMLib can be executed after successful setup in the user's system. Firstly a start-up screen with the name of the program will appear as well as a progress bar that indicates the loading status in percent.
Subsequently, the graphical user interface (GUI) that serves to handle YaMLib is initialised. By the time of the first start that is the default interface (see screenshot below) that can be changed later on at any time.
zurück zum Anfang The (default )interface
Several areas of the screenshot serve as links to their specific explanations by mouse click.

Default interface - English layout Menu MediaLibrary Menu PlayList Menu File System menu Title bar Minimize Maximize Content view - category tree Content view - media library Content view playlists Repeat function modi activate/deactivate shuffle Volume control Balance control Control for position in track Start playback Interrupt/Continue playback Stop playback Jump to previous track Jump to next track Displays the current title Close program Open / Close additional Windows (Edit, Staus, Preferences ...)

During the start of the program the graphical user interface (GUI) is loading automatically. At the initial start-up the default skin (see figure) is displayed; this skin will be displayed by occurence of an error while processing other skin files, too.. The default interface offers the whole spectrum of the program functionality to the user; it consists of a bunch of menus, controllers and buttons along with three large display areas to which different functions are applied.. From left to right these three display areas show the following: The particular functions are explained in detail in Chapter 4.
zurück zum Anfang First steps - Experiencing YaMLib
So let's begin now. The program is loaded and ready, and the interface desires to be used. Well, how then can the program be told to play back multimedia files? In principle this can be achieved in three steps.
  1. Read in multimedia files: Using the menu MediaLibrary in the upper window area one will find the entry Add. There, one faces the choice between File and Directory. Via File one is able to select seperate multimedia files, via Directory one may choose entire directories / folders that contain multimedia files. In both cases a box appears in which the location of the contents is asked for. If the desired file or directory is found and marked it has to be acknowledged (Verzeichnis wählen [= choose directory] / Datei(en) wählen [= choose file(s)]). Afterwards, the selected media will be stored in the media library.
    Notice: While choosing single files, more than one file can be marked! When selecting a whole directory, a box appears asking whether subdirectories should be processed as well. (It asks: Unterverzeichnisse auch laden? That is Load subdirectories, too? in English. Ja = Yes, Nein = No).
  2. Create a playlist: Now that some media files are hold in the media library one's favorite tracks may be combined to a playlist..
    Using the menu PlayList the entry New List can be found. By clicking this line, a box appears, asking for the name of the future playlist (Name der neuen PL [= Name of the new PL]). When this is done, the OK button has to be clicked, and afterwards the new list name appears in the rightmost display area as well as in the playlist tree in the left one. It can be opened by clicking the name on the left.
  3. Now the tracks to play have to be put from the media library (display area in the middle) into the just created playlist. To do so, there are several possibilities. At first one selects the wished file entries (via mouse click) in the media library area. Once marked, they can either be added to the list by selecting the menu item PlayList - Add File, or they can be moved into the list using drag and drop (click, hold and pull the cursor and let the button loose over the playlist area.
Now there's just one click on the Play button remaining undone! The first obstacles are overcome; YaMLib is playing!

zurück zum Anfang Chapter 4: Functions in detail

The following descriptions basically refer to the default skin, which is loaded during the first program start-up (or after occurence of an error while loadling another skin).

zurück zum Anfang The main buttons
At the default interface there are several buttons in the lower left corner of the window that serve to simulate the basic functions of a playing device within the program. From left to right these are:
to start play back of a track (out of the playlist).
to interrupt play back of a track whilst the position within the track will be held. Play back can be continued from the current position by clicking the buttons Play or Pause once more.
to stop play back; the program jumps back to the beginning of the current track, and play back begins from that starting position, if Play is pressed again.
to jump back to the previous track in the playlist order. If play back is active, the current track is stopped and the new track will be played from its beginning. If the current track is at the first position in the playlist, pressing Previous may take effect in two different ways: If Repeat - All is active, the program jumps to the last track in the playlist, if Repeat is deactivated, the program jumps back to the beginning of the current track..
to jump forward to the next track in the playlist order. If play back is active, the current track is stopped and the new track will be played from its beginning. If the current track is at the last position in the playlist, pressing Next may take effect in two different ways: If Repeat - All is active, the program jumps to the first track in the playlist, if Repeat is deactivated, the program jumps back to the beginning of the current track..
Any of these buttons are activated by simply clicking on them.
Notice: The basic functions Play, Pause, Stop, Previous and Next are also available in the Menu File. Their effect is exactly the same. If Repeat – One is active, pressing Previous or Next will cause the program to jump back to the beginning of the current track.
zurück zum Anfang Repeat, Shuffle
On the default skin above the main buttons in the lower left of the window there are settings for the functions Repeat and Shuffle. Both of these influence the habits of the playlists.
There are three different kinds of Repeat modi in YaMLib die can each be accessed by clicking the radio button next to the corresponding entry. In particular these are:
Activating this modus will cause YaMLib to play the whole playlist until reaching its end and then stop after playing until the end of the last track.
This function takes effect in the endless repetition of the current track in the playlist.
If the repeat function All is selected, the program will jump back to the beginning of the playlist and continue play back after finishing the last track..
If this function is activethe program won't jump to the next title in playlist as usual but plays a random track (out of the current playlist). If Shuffle is deactivated, the playlist will be processed in the given order. Activation of the function Shuffle is shown by a check mark in the little box next to the function name. It can be changed by clicking on that box.
If Shuffle is active, the selected repeat modus is ignored by the program. The states of the functions Shuffle and Repeat will be saved when the program is closed.
zurück zum Anfang Jumping within tracks
In the lower right of the default interface window there's a progress bar which shows the current relative position within the track while play back is active. The initial state of the progress pointer is the leftmost position.
During play back dragging the pointer (press and hold the mouse button and pull the cursor) to a specified position will cause the program to jump to that position in the track. Play back will then continue from the given position. Jumping forward and backward in a track is possible at any time.
zurück zum Anfang Adjusting volume and balance
In the lower window area, there are two additional controllers, that influence the habits of the play back. when they are adjusted.
This controller regulates how loud the tracks will be played. Moving the controller to the left decreases the volume while moving to the right increases it.
This controller manipulates the access to the stereo channels of the sound device. Basically the controller rests in the middle position which means, that both, left and right, channels are accessed equally. If it is moved to the left, the program's audio output will end up in the left channel with higher priority, if the controller is set to the leftmost position, the audio signal is sent to the left stereo output device only. The same things happen regarding movement of the controller to the right and the right audio channel.
The position of both controllers will be saved when the program is closed.
zurück zum Anfang Play back of streams
Via File – Open Stream a new window is opened asking for the web address of a multimedia stream. By clicking Open the path is taken over and the stream is played back.
zurück zum Anfang Media library (ML)
The media library serves as the management instance of YaMLib. Here all information about the available multimedia files is stored and arranged. The media library comes up with several kinds of categories in which the particular tracks can be classified as well as various options to search for files, so that the user faces many possibilities to archive, manage and easily find his favorite tracks. For the usage of the media library functions, the menu MediaLibrary in the upper left holds the following entries:
zurück zum Anfang ML - Adding files
In the menu the entry Add can be accessed, opening a sub menu with the following options:
This entry gives the possibility to add single files to the media library. By clicking it, a box appears, demanding the user to search multimedia files within a desired direcotry where these files can be marked and thus selected. A click on Datei(en) wählen [= select files] confirms the selection and the files are added into the media library.
Upon selection (clicking) of this entry a window appears, in which a directory containing multimedia files that are to be added to the media library has to be selected. If such a directory is found, it has to be marked by clicking at its name once and confirmed by clicking Verzeichnis auswählen [= select directory]. Afterwards, a dialog box pops up and asks whether the program should scan subdirectories of the specified directory or not. By clicking Ja [= Yes] it will do so, by clicking Nein [= No] only the directory itself is scanned for media which will then be added to YaMLibs media library.
zurück zum Anfang ML - Removing entries
To remove entries from the media library, they have to be selected in the middle content view that displays the library content. Afterwards, these entries can be removed via the menu MediaLibrary and its entry Remove, whereas two options can be chosen:
Remove - Title:
Causes deletion of the selected entries from the whole media library. Entries being deleted this way are removed from any playlist containing them, too..
Remove - Remove from category:
Causes deletion of the selected entries from the currently selected media category within the media library. Entries being removed this way stay within playlists containing the relating files as well as in the main list of the library.
zurück zum Anfang ML - The specific categories
When adding files to the media library, thei information will be read automatically. Mp3 and Ogg files are arranged in specific meida library lists representing their ID tag information regarding artist, album name and genre. Therefore every file has four initial entries in the media library after being added as listed in the following:
  • Standard entry in the main list (full data base)
  • Entry in the overview of genres [entitled German: Kategorie]
  • Entry in the overview of artists [entitled Germen: Interpret]
  • Entry in the overview of albums
If files do not contain those information, their corresponding entries are arranged in the single categories bearing the title Unknown.
zurück zum Anfang ML - Managing categories
Via a right click menu in the leftmost content view (that holds the categories and the playlist overview) the certain media library categories can be managed. For example tracks that hold no information themselves can thus be easily arranged in a useful manner (e.g. .wav files). Within the menu, there are several options as following:
Add Category:
Using this entry, a new category can be created in the media library. The category represents the genre of a track (Rock, Pop, Metal, etc.). A little window appears, in which the name for the future category has to be typed in. Upon confirmation of the input, the category is added to the media library with its individual name.
Add Interpret:
Equals the function Add Category, while the name represents an artist's name.
Add Album:
Equals the function Add Category, while the name represents an album title.
After masking a category, the name of an artist or the title of an album and selection of this option a box appears, in which a new name for the selection can be typed in. The contents of the selection keep being the same, when it's renamed.
Marking an entry in the leftmost content view and selecting this option causes deletion of the selected category, artist name or album title from the media library.
Media library entries can be moved to any given category, artist name or album title by using drag and drop functionality.
zurück zum Anfang ML - Searching for entries
There's the possibility to search for entries in the media library. This happens using the menu item MediaLibrary - Search. Selecting this, a new window appears, in which the search queries can be sent to theprogram's data base. A request is confirmed by clicking Search. The search results are displayed in the main window within the middle content view (showing the media library contents). To change the content of a search field, it just has to be clicked. Input can be changed via the keyboard. If another search is to be done, the fields can be cleared again by clicking Clear Search. The following criteria (or combinations of them) can be used to search for specific tracks:
This is the unique number identifying the multimedia file in YaMLib's media library.
Pfad [= path]:
With this, a search depending on a complete or partly known file path can be performed.
Titel [= Title]:
This field makes the search depending on track titles as mentioned in the id tags possible.
Nummer [= Number]:
This field demands a track number. Results for this kind of search are tracks, that carry this specific track number in their tags..
Jahr [= Year]:
The query here is a year number, and search results are those files, that come up with that certain year in their ID-tags.
Bewertung [= Rating]:
Via tag-editing a rating can be provided with single entries of the media library. Files that are rated this way can be searched for here.
Interpret Name & Interpret Jahr [= Artist Name & Year]:
Information about the artist who performed the track are stored in these tags.
Album Name & Album Jahr [= Album Name & Year]:
In these fields, the contents of the album tags can be used to perform a search.
Kategorie Name [= Category/Genre]:
This search query looks up the Genre/Category entry in the files' ID-tags.
zurück zum Anfang ML - Simple Search
A faster possibility to search for entries in the Media library is the Simple Search. Choosing this option, a window with an input box appears, in which a specific search string or number can be typed in. The media library is then scanned for matching contents after committing the query.
Notice: For every single data base entry within the media library (id-tags as well) is checked, the Simple Search may take a long time, depending on the amount of multi media data.
zurück zum Anfang ML - Editing entries (ID-tags)
If an entry's ID-tags in the media library have to be changed, the file has to be marked/selected at first. By then clicking MediaLibrary - Edit a new window comes up providing the functionality to edit the tags of multimedia files (ogg, mp3). In addition, there are some inalterable information provided as file properties. Using the button GetMedia the file information is loaded into the particular fields and can be edited there. The altered information can be stored within the file by clicking Update. In detail, the edit fields show the following:
This is the unique number identifying the multimedia file in YaMLib's media library. This information cannot be altered.
Pfad [= path]:
Here, the complete file path within the system is displayed. This information cannot be altered.
Titel [= Title]:
Here, the title, as set in the title tag of the file, is displayed.
Nummer [= Number]:
The track number (basically equalling the track number within an album) is the content of this field.
Jahr [= Year]:
Year of the first publishing of the track.
Bewertung [= Rating]:
An individual rating for a track represented by a number. This information does not depend on the track's ID-tags and is solely stored as an additional information in YaMLib's media library.
Interpret Name & Interpret Jahr [= Artist Name & Year]:
Information about the artist who performed the track are stored in these tags.
Album Name & Album Jahr [= Album Name & Year]:
In these fields, the contents of the album tags are displayed.
Kategorie Name [= Category/Genre]:
This represents the content of the ID-tag for the track's category/genre.
zurück zum Anfang Playlists (PL)
Playlists serve as an ordered set of tracks to play, that can be built by individual means. For example, a user could wish to hear his favourite track twenty times followed by another track; he is provided with this functionality by the playlists. There is no limitation in size and number of the playlists, so that lists with only one entry can be built as well as ilk with a thousand or more tracks in them.
For the media library is solely obliged to manage the multimedia files excluding the play back functionality, YaMLib's player functions depend on playlists and can't be accessed without using them. The functions to manage the playlists themselves are explained in the following:
zurück zum Anfang Creating new lists
By clicking Playlist - New List, a new window appears, asking for a name for the future playlist (it says Name der neuen PL? [= Name of the new PL]). The input is confirmed by pressing OK, and the name of the new list appears in the left displaying area as a sub-entry of the playlist overview (the playlist overview can be opened and closed via double clicking it).
zurück zum Anfang PL - Adding entries
To add multimedia tracks to a playlist, the latter has to be opened first. Afterwards the desired tracks can be selected in the middle, the content view for the media library lists. These can now be moved to the playlist using the menu entry Playlist - Add File from MediaLibrary or directly via drag and drop (click, drag with pressed button and let the button loose at the desired destination) from the middle to the rightmost displaying area
zurück zum Anfang PL - Removing entries
If entries from an opened playlist are to be removed, they have to be marked at first (by clicking). After having done so, the menu entry Playlist - Remove - Title, being clicked, serves to remove the selected entries from the given playlist. Deleting entries from playlists won't alter the media library. The files are still avaiable there..
zurück zum Anfang Selecting a playlist
At the start-up of YaMLib the playlist overview is displayed in the left content view (in closd state at first) This overview can be opened (and closed again) by double-clicking Playlists, a list stored within it can be accessed via a single click on its name.
While a list is opened but one wishes to access another one, the name of that list can also be selected (thus opening the list) at any given time.
zurück zum Anfang Deleting a playlist
If a given playlist is to be deleted, this is possible using the menu entry Playlist - Remove - Playlist. The list then will disappear from the playlist overview and is deleted with all its content
zurück zum Anfang ML / PL Preferences
In the Window menu there's an entry ML / PL - Preferences which, being accessed, brings up a new window. Within this the display settings for the listings of tracks in playlists as well as in the media library categories can be changed. There are options for the access of title, artist (interpret), album name, year, file path and others. Those can be selected or deselected each by clicking and thus showing or hiding a check mark. Also, the single entries can be brought into another order using drag and drop. An additional pulldown menu offers the possibility to sort the entries of thedisplayed media lists in lexicographical order regarding one of the given options. Clicking the corresponding button is enough to cause the program to take oer the settings and save them for future usage.
zurück zum Anfang Changing skins
YaMLib comes up with the possibility to design and load different interface skins and thus being able to fit one's individual needs and wishes. Right clicking on a free place below the three main display areas of the program window brings up a small menu holding the entry Skin laden [= load skin]. When this entry is clicked, another window comes up, where a fitting skin file within the file system can be picked. If such a file is chosen and marked, it is acknowledged by clicking Skin laden [= Load skin]. The program loads now the selected skin.
Notice: The skin files for YaMLib are created in XML format (file extension .xml) and contain specific descriptions of the certain window elements and program functions..
zurück zum Anfang Adjusting the window size
There are different possibilities to adjust the window size and thus fit one's individual needs.
Title bar:
Double clicking the title bar (at the top) of the program window enlarges it to the full surface of the screen. If the window is in full-screen mode yet double clicking the title bar will effect in the deminishment back to the size it had before.
System menu:
In the upper left corner of the program window there's a square shaped icon. Clicking this lets the system menu appear. Here, the entries Maximize, Minimize and Size can be found. Maximize enlarges the window to full-screen mode, while Minimize reduces the window to icon size or into the task bar from where it can be brought back to normal size by clicking it. If Size is selected, the cursor will turn into an arrow cross. The window size can now be adjusted using the cursor keys. The left and down cursors decrease the window size, while up and right serve to increase it. The changes are acknowledged when Return is pressed, and the program will then take them over.
Upper right corner (Minimize / Maximize):
In the upper right corner of the window there are three icons, of which the left and the middle can influence the window size. The left one minimizes the program window to icon size or into the task bar of the system via mouse click. The symbol right to the latter serves to maximize the window to full-screen mode.
Window corners / Window borders:
Moving the mouse cursor over the corners or border lines of the program window will change it to a double-sided arrow (diagonal for corners, horizontal or vertical for borders). If now the mouse button is pressed, the size program window can be individually increased or decreased by dragging the corner or border to the wished destination. When the mouse button is let loose, the program window will switch to the chosen size.
zurück zum Anfang Closing the program
Even for closing the program, there are several options.
System menu:
Clicking the icon in the upper left corner opens the system menu where the entry Close can be found. Using this will stop the program execution and close it.
Menu File:
In the menu File (in the upper window area) the entry Close can be found, that causes the program to exit and close when being clicked.
Upper right corner
The quickest way possible to stop and close the program is clicking the X-Icon in the upper right corner of the program window.

zurück zum Anfang Chapter 5: About YaMLib

This section provides some information about the makers of YaMLib as well as about its programming.

zurück zum Anfang YaMLib's makers
YaMLib has been planned, designed and coded as a team project of the programming group I of the "Softwaretechnik-Anfänger-Praktikum" in summer semester 2004 in the Department 12 of Philipps-University of Marburg.
The coders in detail:
Antje Schultz
Benjamin Weber
Daniar Achakeyev
Daniel Rudolph
Daniel Wenske
Dennis Bock
Dominic Finke
Florian Schwarz
Gassan Gousseinov
Gregor Bonifer
Ivo Pacák (Tutor)
Jan Königsfeld
Jan Neuvians
Jörn Ruhlender
Karsten Kopjar
Ke Jin
Khalid Ballafkir
Lars Baumgärtner
Lyuben Manolov
Magnus Dau
Matthias Weigand
Michael Lemler

Miroslav Petrov
Nasim Mofidian
Robert Socol
Simone Pulch
Slawomir Messner
Tanja Reinhold
Timm Meyer
Timo Steiner
Tonio Koletzky

Ulrike Georgi
Yuchen Deng

zurück zum Anfang Used system
YaMLib has been coded in the programming language Java (in version 1.4.2 of the SDK (Software Development Kit) of Sun Microsystems. Mainly the IDE (Integrated Development Environment) Eclipse has been used to build the program. As developing and testing machines, several differently configured systems were in use (with Windows 98, XP and Linux platforms).
zurück zum Anfang The program license
YaMLib is free for public use, regarding the GPL (GNU General Public License) guidelines and thus the guidelines of Open Source. Provided that the names of the originators of the program are mentioned, distribution and duplication of YaMLib as well as the alteration of the source files of the individual program components are permitted without limitation. More information about Open Source can be found at this address: http://www.opensource.org/docs/definition.php. The proper GPL specification is available at this site as well as at: http://www.gnu.org/copyleft/gpl.html
Exception to the terms mentioned above is the graphical user interface (GUI). The latter is provided free upon kind approval by Mr. Timm Meyer ( http://www.mathematik.uni-marburg.de/~timmm ) for the users of YaMLib, but it may not be altered regarding its state and constitution. The GUI source files may neither be decompiled nor used in other programs. Breach of these rules means to infringe copyright and is thus avenged by juridical penalty.

zurück zum Anfang Chapter 6: Questions and answers

zurück zum Anfang Why are there some German expressions in the program?
There's a simple explanation to this question: YaMLib initially was designed for German users by German coders. It provides the possibility to design English labeled skins, but some of the buttons and other items are labeled German within the source code which can't be renamed by "simple" skinning. We regret this, but hopefully this manual helps you understand them anyway. If any translation is neccessary, it is provided within the relating explanation of the function.