Copyright (c) 2008 W. Park Cram
<parkcram |at| users |dot| sourceforge |dot| net>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
INTRODUCTION
Musiql is a frontend to MPlayer and SQLite that lets you play music from the
command line while still having access to the database and playlist features of
a media player like iTunes, Amarok, or Banshee. You select which songs to play
by entering SQL queries (or, more precisely, the WHERE clause of a SQL query).
Musiql plays the songs you requested using MPlayer, giving you access to all of
MPlayer's usual keyboard shortcuts, including next and previous track keys for
navigating through the playlist. You can also pass options through to MPlayer,
giving you access to features like shuffle and repeat.
Musiql also keeps track of how many times you've played a song, and when you
last played it. You can control how much of the song must be played before
Musiql updates the database. Musiql will also submit track information to
Last.FM if you set up lastfmsubmitd and enable reporting in your config file.
Musiql can import files into the database, using Mutagen to extract metadata
from the tags. It should support all of the file formats Mutagen can detect,
but only the mp3 and mp4 support is thoroughly tested. The support for APEv2
tags is totally untested, so any feedback regarding it is appreciated. Musiql
can sync its database to a given directory, adding any new files to its
database and deleting the database entries for files that no longer exist.
INSTALLATION
Dependencies
Python 2.5 (http://www.python.org)
pysqlite2 (http://www.pysqlite.org)
SQLite3 (http://www.sqlite.org)
mplayer (http://www.mplayerhq.hu) - any recent version should work, just
make sure your version can play all
of your music files
Mutagen (http://www.sacredchao.net/quodlibet/wiki/Development/Mutagen)
- tested w/version 1.13-1
If you want Last.FM submission:
lastfmsubmitd (http://www.red-bean.com/~decklin/software/lastfmsubmitd/)
- tested w/version 0.37-2
Download the latest release version of Musiql from:
http://sourceforge.net/projects/musiql
Or get the latest development version from subversion:
svn co https://musiql.svn.sourceforge.net/svnroot/musiql
If you download the release tarball, unzip it:
tar -xzvf musiql-0.0.20080601.tar.gz
Then change into the new directory:
cd musiql-0.0.20080601
Run the following command as root (or using sudo):
python setup.py install
This will install into /usr/bin. If you want to install to /usr/local/bin,
instead do:
python setup.py install --prefix=/usr/local/bin
To run Musiql:
musiql
Try 'musiql --help' for information on options and arguments.
The first thing you will want to do is import some music:
musiql -I /path/to/music
Then enter a query to select the tracks you want to play:
musiql "Artist LIKE 'The Velevet Underground'"
For more information on query syntax, see the SQLite website
(http://www.sqlite.org). For a list of the database columns, see below. Keep
in mind that Musiql gets this information from the tags in the file, so if your
library is poorly tagged, you will get poor results.
CONFIGURATION
Musiql will look for configuration files in $HOME/.musiqlrc and
$HOME/.musiql/musiqlrc. You can put your config file in either location (if
for some reason you create both, settings in .musiql/musiqlrc will override
those in .musiqlrc). Each line should contain an option=value statement.
Lines beginning with '#' will be treated as comments. Note that inline
comments are not currently supported, though. There are currently several
options you can set.
lastfm
Set to 'True' or 'yes' to enable submitting information to Last.FM.
This will only work if lastfmsubmitd is installed and configured correctly.
lastfmsubmit_path
A string containing the full path to the 'lastfmsubmit' script. This is
usually '/usr/lib/lastfmsubmitd/lastfmsubmit' (in Debian, at least), and if
this is the case on your system, you do not need to set this option. If it
is installed somewhere else, though, you need to point Musiql to its
location. If it is installed to a directory in your path, 'lastfmsubmit'
should be sufficient here.
submit_point
Controls how much of the song must be played before information is
recorded in the database and submitted to Last.FM (if enabled). Can be
any value between 0 and 1.
defaultdb
The location of the database to use by default. The default is
'$HOME/.musiql/musiql.db'.
default_sync_dir
The directory to sync to if you run 'musiql -I' with no arguments. This
starts out pointing to nowhere, so 'musiql -I' will do nothing. Point it
to your music library if you want to make syncing easier.
follow_symlinks:
Set to 'True' or 'yes' to follow symbolic links to directories when
importing or syncing directories. Unset by default.
USAGE
You can get a summary of Musiql's options by running 'musiql --help'. The
basic argument is the WHERE clause of a SQL query to your music database.
Musiql will automatically prepend 'SELECT * FROM Tracks WHERE' to your query,
so you should leave out that part. The fields in the default Banshee database
that you can use to search on are:
TrackID INTEGER PRIMARY KEY,
Uri TEXT NOT NULL,
MimeType TEXT,
Artist TEXT,
Composer TEXT,
Performer TEXT,
Conductor TEXT,
Lyricist TEXT,
AlbumTitle TEXT,
ReleaseDate DATE,
Label TEXT,
Title TEXT,
Subtitle TEXT,
Genre TEXT,
BPM INTEGER,
Year INTEGER,
TrackNumber INTEGER,
TrackCount INTEGER,
DiskNumber INTEGER,
DiskCount INTEGER,
Duration INTEGER,
Rating INTEGER,
NumberOfPlays INTEGER,
LastPlayedStamp INTEGER,
DateAddedStamp INTEGER
One nice feature in SQLite is the REGEXP operater, which works like LIKE, but
matches using regular expressions instead of only giving you wildcards.
There are a few special character sequences that Musiql recognizes in queries
and replaces. These are:
~s Insert the 'SELECT * FROM Tracks WHERE' part of the clause.
This is done automatically at the beginning of the query, so
you only need it if you are doing a compound query. You should
use this instead of including the SELECT manually, so that you
don't have to worry about grabbing all the columns Musiql needs
in the right order.
~p'PATTERN' Insert a query that selects all songs in playlists with names
matching PATTERN, using SQL LIKE (with % as wildcard) for
matching. This inserts an entire SELECT statement, with no
need for any additional information from the user.
~P'PATTERN' Same as ~p, but uses REGEXP instead of LIKE.
~v'VIEW' Insert a query that selects all songs from the view named
VIEW. This will only match exact hits (no regular expressions
or wildcards are allowed). A view is a stored SELECT query.
It provides functionality similar to a smart playlist in
iTunes.
~d'DATE' Convert DATE from human-readable format to the machine's time
format (seconds since 1970 on UNIX systems). This is useful
if you want to search on the LastPlayedStamp column.
The date should be in the format 'dd Mon yy [HH:MM]'
(%d %b %y [%H:%M] in strftime format). The brackets indicate
that the time part is optional (i.e., don't include them).
For example, ~d'19 Apr 08' or ~d'19 Apr 08 23:00'.
Musiql will only execute a single statement, but you can issue compound SELECT
statements joined by UNION, UNION ALL, INTERSECT, or EXCEPT. For a complete
list of the SQL syntax supported by Musiql, see the SQLite website, bearing
in mind that Musiql only allow you to submit SELECT statements, and even
then, only the section following WHERE.
Once Musiql starts, it passes any keyboard input except the 1-5 keys through to
MPlayer, so you can control playback normally. The 1-5 keys are used to rate
songs. If you press one of these keys, it will update the song's rating in
your database. You can then write queries that select songs with particular
ratings. These keys normally control contrast, brightness, and hue in MPlayer,
so you shouldn't miss them while playing audio.
DATABASE INFORMATION
Musiql stores information about tracks in an SQLite database. The format was
initially based on the format used by Banshee, but Musiql now creates several
fields, such as Composer, that Banshee does not, and it leaves out some fields
and tables used by Banshee, so the databases are no longer 100% compatible.
That said, you should be able to play songs from a Banshee database if you
want. You will not, however, be able to import songs into a Banshee database.
The schema for the Tracks table is reproduced above. The schemas for the
playlist-related tables are below.
CREATE TABLE Playlists (
PlaylistID INTEGER PRIMARY KEY,
Name TEXT NOT NULL,
SortColumn INTEGER NOT NULL DEFAULT -1,
SortType INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE PlaylistEntries (
EntryID INTEGER PRIMARY KEY,
PlaylistID INTEGER NOT NULL,
TrackID INTEGER NOT NULL,
ViewOrder INTEGER NOT NULL DEFAULT 0
);
CONTACT INFORMATION
For more information about Musiql, or to file bug reports or find a link email
the author, visit http://sourceforge.net/projects/musiql.