Prokyon3


Table of Contents

1. Introduction
1.1. Overview
1.2. Features
2. Installation
2.1. Linux
2.2. Windows
3. Usage
3.1. First Time Usage
3.2. Create a new database
3.3. Search for your musical files on the Hard disk
3.4. Play your Music
3.5. Manage your musical files
3.6. Settings
4. Musicextras
4.1. What it does
4.2. How to Start a Search
4.3. Musicextras Menu
4.4. Configuration
5. Frequently Asked Questions (FAQ)
5.1. Generic
5.2. Linux
5.3. Windows

Chapter 1. Introduction

1.1. Overview

Thank you for downloading Prokyon3.

Prokyon3 is a multithreaded music manager and tag editor for Unix (developed on Linux). It was written in C++ using the Qt3 widget set and the MySQL database. prokyon3 can access MP3, Ogg and FLAC files on harddisk, CDROM, SMB and NFS. Files can be played using XMMS (default) or other players. The file view is customizable and favorite artists are supported. prokyon3 also offers an editor for ID3 and Ogg tags and has been designed to support tagging for large quantities of files.

Additional information and links can be found at http://sourceforge.net/projects/prokyon3.

We can be contacted using Prokyon3 Help and Open discussions forums http://sourceforge.net/forum/?group_id=47522.

The Prokyon3 development team

1.2. Features

Prokyon3 key features are:

  • multithreaded (Qt3 based versions only)

  • manages music files on harddisk/cdrom or over network

  • search the database by artist, song, album, filename...

  • very comfortable editor for ID3 tags

  • manages favorite artists

  • plays or enqueues music files with XMMS, WinAmp and a lot of different players

  • uses MySQL as database backend

  • configuration editor and database wizard

  • access files over SMB and NFS (Linux only)

  • playlist editor

  • support for MP3/Ogg/FLAC

  • access tracks by artist and album

  • support for different album types (normal, sampler, soundtrack, musical, drama, comedy)

  • basic drag-n-drop support (Linux only)

  • Microsoft Windows port (poor performance due to qt2 backport)

  • smart playlist generator

  • cd burning via k3b (supports Audio CD, Data CD, Data DVD) and prokburn

  • save GUI setup

  • localization

  • taglib support

  • guess tags from path and filename dialog using regex

  • musicextras integration (get album covers, artist images, lyrics, ... from the internet and store it within prokyon3)

  • support for embedded MySQL including wizard

  • personal review notes

  • rating of tracks

  • generator takes care of rating

  • allow customized SQL queries (free MySQL search) and store them

  • export and import playlists (m3u and pls)

  • copy tracks to directory (useful for mobile mp3 players)

  • preconfigured for several popular players (xmms, amarok, totem)

  • Mixxx remote control and Mixxx queues

  • basic MusicBrainz support

  • supermount and submount support

  • album cover thumbnails

  • utf8 support

  • 64bit platform support

Chapter 2. Installation

2.1. Linux
2.2. Windows

2.1. Linux

2.1.1. Compile from Source

Prokyon3 is mostly available as a source tar file. It uses GNU Autotool and in most case, compiling and running Prokyon3 on a Linux box consist of:

  1. Download and untar latest stable project archive from http://prokyon3.sourceforge.net

    user#>tar -zxvf prokyon3-XXX.tar.gz
  2. Configure and compile.

    user#> ./configure
    user#> make
    root#> make install
  3. Create the database

    Create a database and setup the parameters in the configuration dialog .

    [Note]Note

    As an alternative, with MySQL 3.22 and later, you can use the 'create new database' wizard in the file | menu....

  4. Fine tune your configuration with File | Settings

Please refer to ./configure --help to fine tune compilation for your system.

CD burning is optionaly achieved via a bash script (prokburn) installed in your binary directories (/usr/local/bin by default). This script will do all necessary format conversion and ajustement and will burn a CD for you.The following programs are required by prokburn in your $PATH.

Table 2.1. Key programs required by prokburn script

NameFunction
mpg123Decoding mp3 files to wav.
ogg123Decoding ogg files ro wav
normalizenormalizing tracks audio volume program available at http://www.cs.columbia.edu/~cvaill/normalize/
cdrecordCD burning.

You will need free disk space in your $HOME/tmp directory. The minimum corresponds to your total CD size. Please feel free to edit prokburn to fit your needs, It was written as a late evening exercise and it can be improved in many ways. Please do email us patch and update so we can include it our next prokyon3 release. On this specific topic, we will strongly recommend reading the excellent "Linux MP3 CD Burning mini-HOWTO" from Greg Wierzchowski. It is available online at http://www.tldp.org/HOWTO/MP3-CD-Burning/index.html.

[Note]Note

prokburn will assume SCSI target 0,0,0 for your cd burner. If this is not the case, you will have to edit the prokburn script in your install directory.

2.1.2. Binaries

There are some. We know that there's a debian package available and we discovered some gentoo ebuild scripts (well, that's not a binary ;-) ).

2.1.3. Troubleshootings

Here is a list of [gotcha's] that may prevent prokyon3 from running once compiled properly.

  • Make sure the environment variable QTDIR points to the right directory (Debian/Woody: '/usr/share/qt')

  • Make sure you provide the correct MySQL superuser user and password to the wizard.

  • Do not forget to connect to the database by clicking the 'connect' button.

See also FAQs here .

2.2. Windows

2.2.1. Prokyon3
2.2.2. MySQL Server
2.2.3. WinAmp

2.2.1. Prokyon3

Installing Prokyon3 is straightforward using a self-contained binary zip package. Just open the archive and double click on setup.exe.

[Warning]Warning

Prokyon3 was developed by a team of enthusiastic people as an open source development product. As such we strongly advocate use of non proprietary operating system. Prokyon3 was mostly written on Linux OS using open source development tools. However we recognize that not everybody is having access to a computer running Linux. We considered our Windows port as a "demo" version. It is definitely not as good as it's Linux counterpart.

We hope the Windows version will give you a good overview of Prokyon3 ability and encourage you to set-up a Linux PC quickly to run it on a non proprietary OS.

The main restriction that apply to the Windows version is a lack of multi threading support. This result in slow operation when intensive CPU tasks are performed. Concerned are mostly commands involving files synchronizing. It is also somehow lacking remote file support.

[Note]Note

You will need to install two other programs before running Prokyon3 on Windows:

  • MySQL

    Alternatively it's possible to connect an MySQL server running on a Linux box ;-)

  • WinAmp

See also FAQ here .

2.2.2. MySQL Server

All tests were made using release 3.23 for Windows. You can download it from http://www.mysql.com/downloads/mysql-3.23.html. Just run the installer and make sure you have a running server. You will notice a small traffic light in your system tray. It must be green. If not, try to right click the icon and run the server manually.

You absolutely must have a running MySQL server for Prokyon3 to run. While you are at it, double click again on the icon, select "show me" and look at the default user and password under "myini Setup" tab.

2.2.3. WinAmp

WinAmp can be downloaded from http://www.winamp.com/download. You recommend to use Winamp3. Previous version (i.e. Winamp2) will run as well, but there is some limitation to the command line length: Winamp2 will crash if you try to play a long play-list. And if you are unlucky enough to use win98 you probably will have to start Windows again. So try to use Winamp3. It is a bit slow to start but after that it is very stable and you can expect future versions to improve start-up time. The installation of WinAmp is straightforward.

Chapter 3. Usage

3.1. First Time Usage

When you run Prokyon3 for the fist time it will detect it and a window will provide detailed help.

3.2. Create a new database

From Prokyon3 select File | Create new database. Use the superuser name and password for your MySQL server. Most probably the default value is OK for your installation (which means that there is no root password required in most cases). You must first create a valid database to proceed any further. A message box will confirm this has been done. Now you should be able to connect to the server with File | connect and get a little smiling face in the status bar at the bottom of Prokyon3. If this is the case, just relax, you are nearly done (see also FAQ here).

3.3. Search for your musical files on the Hard disk

After selecting your search path with File | settings | Directory (see FAQ here) then right click in the hard disk button at the lower left bottom of the screen. Choose Synchronize (Prefer sources) for the first time.

3.4. Play your Music

Right click on a musical file in the middle window and choose PLAY Tracks. If nothing happens, check your play and enqueue command lines in File | Settings | Toggle. Try to run your play command directly from a console. If you did not install in a standard location you will have to edit both commands.

3.5. Manage your musical files

You can select one or several files and edit all tags via the Edit button.

[Note]Note

When your are in edit mode, pay special attention to the button available to the right side of each editable fields. It has two specific modes of operation (See also FAQ here ).

  • When right clicked, a field specific menu will pop-up.

  • When left clicked, change will be copied to all tracks.

Modifications are immediately recorded into Prokyon3 MySQL database when Save button is pressed, but the information embedded into your musical file ("tags") are not changed unless you specifically asked for it. This is done via various synchronize commands. These are found when right clicking on the hard disk icon in the lower left window, from normal mode. Several options are available as described below.

In the following, by files, we mean information from the file system and by tags information kept by Prokyon3 into it's database.

  • Update Only

    New files are read and added to tags. Deleted files are removed from tags. No other tags or files change is taking place. As a result, information from some files can still be different from their tags equivalent.

  • Synchronize

    Same as Update Only command. In addition, write modified tags to files and read tags from modified files. As an option, one can prefer tags or files when both have been changed. Both files and tags are modified.

  • Update and Read tags

    Same as Update Only command. In addition, read tags from modified files. As an option one can force read if both files and tags have been changed. Some modified tags may be lost, but files are never modified.

  • Update and Write tags

    Same as Update Only command. In addition, write files from modified tags. As an option one can force write if both files and tags have been changed. Some files info may be lost, but tags are never modified.

[Note]Note

In addition to complete editing and searching capability, Prokyon3 offer some special features:

  1. Favourite Artists

    You can tag favourite artists on the main artist/album list. Once tagged, all favourite artists can be displayed together under the "Fav." tab. Further, play lists can be randomly generated from your favourite artists.

  2. Sampler/Soundtracks

    A similar concept but applying to tracks rather than artists. To flag a Sampler/Sountrack, you will need to edit your track and click on the Sampler or Soundtrack check box in the album information group box.

    Samplers and Soundtracks are listed separately under the "Sampl." tab.

3.6. Settings

Prokyon3 can be further configured with he following options available with file | settings | toggles as detailed below.

3.6.1. "Read ID3v2 tags"

When this box is checked, Prokyon3 will read ID3V2 tags from mp3 files. It will default to V1 if no V2 tags are available.

If unchecked, Prokyon3 will only read V1 tags from mp3 files. ID3V1 tags had some obvious limitations and drawbacks so it is better to leave this box checked. One can find more detailed information about ID3 tags at http://www.id3lib.org.

Default value is checked.

3.6.2. "Write ID3v2 tags"

When checked, Prokyon3 will always write tags as ID3 V2 tags to your file.

Default value is checked.

3.6.3. "Auto connect to database at startup"

Once your Mysql base is running and your connection is OK, this box should be checked.

Default value is unchecked.

3.6.4. "Auto hide artists/sources/playlists in tag edit mode"

When checked, Prokyon3 will hide play lists and artists tree when tags are edited. This will expand your display during edit mode.

Default value is checked.

3.6.5. "Never show content of whole hard disk|SMB shares|NFS exports"

If checked, Prokyon3 will not attempt to display all you files in a single list when, for example, you click the Harddisk button form the Media tab in the selector. Useful if you have lots of files on your hard disk|SMB shares|NFS exports as this can be painfully slow.

Default values are unchecked.

3.6.6. "Allow tool tip"

Get rid of pop-up help messages.

Default value is checked.

3.6.7. "Allow column to expand automatically"

When checked, columns size will be adjusted automatically by Prokyon3 to match displayed text width.

When unchecked, Prokyon3 will remember your manual column width adjustments and restore it between sessions. These will not changed unless you modify them manually.

Default value is checked.

3.6.8. "Allow Gui configuration restore"

When checked, internal frame sizes, as well as relative columns position in listing views will be saved and restore between sessions. In a similar manner, if some main frames are hidden by the user, this will be saved and restored by Prokyon3.

Default value is checked.
[Note]Note

However, Prokyon3 will always automatically save an restore the following Gui information:

  • Position and size of the main window on the desktop.

  • User-selected field information displayed in the central frame.

  • Search file path.

  • Database connexion parameters.

3.6.9. "Play and enqueue commands"

Play command must cancel and reset any existing play list already loaded into your favourite player. Enqueue command will be used to add your selected tracks to the current one. Selected tracks are passed as additional arguments to these commands.

Default value are OK with xmms.

3.6.10. "BurnCD command"

BurnCD command will write a CD with currently selected play List. Selected tracks are passed as additional arguments to this command.

Default to "prokburn" script supplied as part of Prokyon3 package.

Chapter 4. Musicextras

4.1. What it does

Musicextras is a program that automatically retrieves extra information on music tracks. It searches a number of internet sites for data on the artist, the album and the song title. If the optional Musicextras support of Prokyon3 is activated at compile time Prokyon3 is able to display

  • Artist image
  • Album cover
  • Track lyrics
  • Album review
  • Artist biography

if the corresponding data can be found by Musicextras on the internet sites.

4.2. How to Start a Search

There are two ways to operate Musicextras from inside Prokyon3:

  • Single track scan: You can initiate a Musicextras search for a single track by selecting the track in the central track list and by hitting the "WWW Scan" button on the "Extras" tab in the right pane.

  • Complete collection scan: You can initiate a scan of your complete music collection by selecting the "Scan all" action from the Musicextras dropdown menu.

4.3. Musicextras Menu

  • Musicextras log: View the Musicextras log in a separate window. This allows you to track the progress during a scan of the complete music collection, for example.

  • Scan all: Perform a Musicextras search for the complete music collection in turn.

  • Zap cache: Delete the Musicextras cache.

  • Abort scan: Abort a running Musicextras scan.

4.4. Configuration

Prokyon3's settings menu contains a Musicextras tab that allows you to fine-tune the Musicextras functionality.

  • Background cover: Whether a toned-down version of the album cover is to be used as background of the track list.

  • Number of concurrent web access threads: Sets the maximum number of Musicextras instances that are allowed to run in parallel. This can be useful for speeding up the Musicextras search but too high a number of connections may be considered abuse by your connection provider or by the providers of the web sites that offer the music data.

  • Artist image: Whether the artist image is to be retrieved.
  • Album cover: Whether the album cover is to be retrieved.
  • Track lyrics: Whether the track lyrics are to be retrieved.
  • Album review: Whether the album review is to be retrieved.
  • Artist biography: Whether the artist biography is to be retrieved.

Chapter 5. Frequently Asked Questions (FAQ)

5.1. Generic
5.2. Linux
5.3. Windows

5.1. Generic

5.1.1. "Do I need to connect manually to the database each time I start Prokyon3?"

No, You can enable auto-connect feature in File | Settings | Toggle.

5.1.2. "What directory should be included in File | Settings | Directory?"

Indicate where all your Ogg and MP3 files are located. But do not enter a CD path. Prokyon3 will automatically look in all sub-directories. In theory you could put your hard disk root there ("c:\" or "/") but it may take a long time to scan.

5.1.3. "How are CDs handled?"

First insert a CD, then right click on the CD icon and select Append to Database. This will compute a unique CD ID and scan the removable disk for musical files. When the CD is loaded/unloaded corresponding Artist/title from the list will be highlighted/grayed out.

5.1.4. "Can I edit several tracks at the same time?"

Yes, you can. Select them in the middle window, and edit them. Although only one track is selected at any time, you can still apply a change to the whole selection by left clicking the grey square button at the right of any tag field. Right clicking on the same button will give you more options.

5.1.5. "What is the play list generator about?"

This will automatically generate a play list picking random tracks from your library. Very Handy....

[Note]Note

Only tracks available on hard disk are considered at the moment.

5.1.6. "These pop-up windows (tool tips) become quickly a real nuisance..."

You can disable them permanently via File | Settings | Toggle.

5.1.7. "What is the Andromeda option for?"

This option is available in edit mode, when right clicking on the square button associated to filename field. The Andromeda option assigns a filename to a track, so it is lexically in the right order including the order of track numbers. It was implemented from the great PHP-Script Andromeda. An Andromeda filename consists of the artist name, followed by the album abbreviation, a track number and finally title of the track.

By consistently using Andromeda file name, a simple alphanumeric sort will classify your tracks by artist, album and track number.

5.1.8. "Is searching using regular expression supported?"

All Mysql standard Rexpep are supported. With Mysql 3.0., characteristics of extended regular expressions are:

  • `.' matches any single character.

  • Character class `[...]' matches any character within the brackets. For example, `[abc]' matches `a', `b', or `c'. To name a range of characters, use a dash. `[a-z]' matches any lowercase letter, whereas `[0-9]' matches any digit.

  • `*' matches zero or more instances of the thing preceding it. For example, `x*' matches any number of `x' characters, `[0-9]*' matches any number of digits, and `.*' matches any number of anything.

  • The pattern matches if it occurs anywhere in the value being tested. (SQL patterns match only if they match the entire value.)

  • To anchor a pattern so that it must match the beginning or end of the value being tested, use `^' at the beginning or `$' at the end of the pattern.

Search is not case sensitive.

Following tags are searched (if and only if checked ): path/filename, artist, title, album,comment.

Search is started when Enter key is pressed or alternatively by pressing the "Start" button.

"Reset" button will reset searched string to blank and "Defaults" will select default search fields list to its original value.

5.1.9. "How can I reset my configuration values?"

By default your config file is located in ~/.qt/prokyon3rc for the Linux version or c:\qt\prokyon3rc for the Windows version.

If you ever run into problems with your saved values, you can delete this file. Prokyon3 will then revert to its default values.

5.2. Linux

5.2.1. "What do I need to compile Prokyon3?"

You will need the following components (and their libraries) installed to compile from source code:

  • A running MySQL server

  • QT3 compiled with both thread and MySQL support enabled

  • id3lib libraries

  • Ogg and Vorbis libraries if you want Ogg support

Here is what ldd tells on SuSE 8.1:

libqt-mt.so.3 => /usr/lib/libqt-mt.so.3 (0x40023000)
libogg.so.0 => /usr/lib/libogg.so.0 (0x40647000)
libvorbis.so.0 => /usr/lib/libvorbis.so.0 (0x4064b000)
libvorbisfile.so.3 => /usr/lib/libvorbisfile.so.3 (0x4066b000)
libid3-3.8.so.0 => /usr/lib/libid3-3.8.so.0 (0x40672000)
libz.so.1 => /lib/libz.so.1 (0x406ad000)
libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x406bc000)
libm.so.6 => /lib/libm.so.6 (0x4076f000)
libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x40792000)
libc.so.6 => /lib/libc.so.6 (0x4079a000)
libpng12.so.0 => /usr/lib/libpng12.so.0 (0x408b8000)
libpthread.so.0 => /lib/libpthread.so.0 (0x408e8000)
libGL.so.1 => /usr/lib/libGL.so.1 (0x408fd000)
libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x40ac8000)
libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40ade000)
libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40af5000)
libdl.so.2 => /lib/libdl.so.2 (0x40afe000)
libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40b01000)
libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40b0f000)
libXrender.so.1 => /usr/X11R6/lib/libXrender.so.1 (0x40c07000)
libXft.so.1 => /usr/X11R6/lib/libXft.so.1 (0x40c0c000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x40c38000)
libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40c7a000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x40c82000)

5.2.2. "What package are required to compile on Redhat (SuSE)?"

Redhat at least by 7.3 has MySQL in a separate rpm from qt-devel. To compile, you'll need both the qt-devel package and something like qt-MySQL-3.0.3-11.i386.rpm

SuSE missed some dependencies, which means that an installation of qt3-mysql.rpm not automatically causes an installation of mysql-shared.rpm and mysql-client.rpm.

5.2.3. "What packages are required to compile on Mandrake 9.1?"

This is the (hopefully) complete list of required packages:

  • libid3lib3.8_2-3.8.2-2mdk

  • libid3lib3.8_2-devel-3.8.2-2mdk

  • libqt3-3.1.1-13mdk

  • libqt3-common-3.1.1-13mdk

  • libqt3-mysql-3.1.1-13mdk

  • libqt3-devel-3.1.1-13mdk

  • libmysql12-4.0.11a-5mdk

  • gettext-0.11.5-2mdk

  • XFree86-devel-4.3-5mdk

  • zlib1-devel-1.1.4-5mdk

  • libmysql12-devel-4.0.11a-5mdk

  • MySQL-common-4.0.11a-5mdk

  • MySQL-client-4.0.11a-5mdk

  • MySQL-Max-4.0.11a-5mdk

  • libvorbis0-1.0-6mdk

  • libvorbis0-devel-1.0-6mdk

  • libogg0-devel-1.0-3mdk

  • libvorbisfile3-1.0-6mdk

  • libogg0-1.0-3mdk

[Note]Note

Prokyon 0.9.2 or higher (or CVS snapshot) is needed to support the creation of the database if MySQL4 is used.

5.2.4. "Which version of the QT library is required?"

Basically any version above 3.0 will work. Please note that there was on-going improvement/bug fixes from Trolltech since the original release. More specifically, multi thread capability of some function was significantly improved. We have found qt3.1.1 (last available at the time of this release) to be more stable and robust than previous versions.

5.2.5. "What version of g++/gcc is required?"

Prokyon3 can be compiled successfully using gcc 2.95 or 3.2. We recommend gcc 3.2 but other versions may work as well. If you are using g++ 3.XX you need to recompile all C++ libraries used by Prokyon3 are these are not binary compatible with g++ 2.XX libraries . C libraries are no problem. Currently, Prokyon3 requires 2 C++ libraries: QT3 and libid3. If you upgrade your compiler, your will need to recompile both libraries to successfully link Prokyon3.

[Note]Note

Prokyon3 v0.9.1-r1 could not be compiled using gcc 3.3 (SuSE 8.2). The next version will compile as well as the current CVS version does ;-)

5.2.6. "How do I compile Prokyon3 on Mandrake?"

One way is to download and compile latest x11 version of QT3 (source tar-ball). It must be configured with the -threads and -plugin-sql-mysql options. In addition, on Mandrake you need the -I/usr/include/mysql option.

5.3. Windows

5.3.1. "What do I need to compile Prokyon3?"

Unfortunately you will need Microsoft Visual C++ V6.0 as Qt Win230 free package is a binary distribution that can only be used with MSVC++ :-( . It is not even guaranteed that it will be compatible with more recent version of the compiler: you must have a try first. The easiest way to get MSVC++ 6.0 is to purchase it second hand over the Internet as I did. In addition you will need the following GPL packages:

Included in the source code you will find a make file compatible with Microsoft NMAKE. I modified it by hand so you should directly run the make file to compile. I never tried to compile from the MSVC++ IDE.

I used Emacs for windows from http://www.gnu.org/software/emacs/windows/ rather than Microsoft IDE for all Windows development.

Microsoft Visual C++ 6.0 has some problems with latest ANSI features and force me to implement lots of minor changes to compile properly. Further I had to "back-port" Prokyon3 from QT3.0 to QT2.0. Unfortunately Qt2.0 was missing any SQL support so I had to provide a minimum wrapper to the mysql++ API to interface with Prokyon3 database layer. As a result it will be a major work to recompile latest Prokyon3 release. My starting point was release 0.9.1.

What is really great is the debugger bundled with Microsoft Visual C++. This is the only point where the Microsoft Visual C++ out-pass Linux development tools IMHO. (Comment from Markus: PHF, try eclipse for windows!)

If you have any more questions about the Windows port, feel free to contact me at paul-henri.ferme@noos.fr.