zicbee /

Filename Size Date modified Message
44 B
1.2 KB
156 B
119 B
1.4 KB
5.3 KB
11.1 KB
5.9 KB
194 B
14.1 KB
14.2 KB
351 B
99 B
3.4 KB
26 B
141 B
7.9 KB

User documentation

For a shorter introduction, see Quickstart page.


Instructions (skip this if you already installed zicbee)

Preferably, download and unzip a packaged release or clone the workshop repository if you plan to hack the code:

~/programs/> hg clone http://zicbee.gnux.info/hg/zicbee-workshop/ bee
~/programs/> cd bee

Now you should be able to run manage program so every source will be retrieved and a compact distribution will be built.

~/programs/bee/> ./manage

You can also install it in the standard setuptools way:

easy_install -U zicbee
pip install -U zicbee

"-U" means update in pip and easy_install.

setuptools or distribute is required for that.

After that, you should have working "zicdb", "wasp" and "zicserve" binaries. Feel free to run execute with "help" as the only argument!

Note that zicserve is just a convenient way to run "zicdb serve".

  • 3.0 > Python >= 2.6
  • or Python 2.5 with:
    • cjson [json]
    • or simplejson [json]
    • or demjson [json]

Knowledges about shell usage and readline is a good point.

  • any shell, preferably with readline enabled [ui_core]
  • webpy >= 0.3 [ui_www]
  • buzhug [database]optional dependencies:
  • mplayer (the open one, mostly known by free software users) [player]
  • vlc [player]
  • python-gst (gstreamer) [player]

For playback, according to the backend, you will need either:

  • mplayer(.exe) in your PATH
  • libvlc available on your system
  • gstreamer + pygst bindings

Once you installed zicbee (unpacking a pack or installing individual packages) on computers with music, run those shell commands on each :

% zicdb scan <base directory containing music files>

wait a little, depending on your library size ...

% zicserve

now the server is looping, you can access the music of this computer remotely (or not ;))

If you installed zicbee-mplayer (or vlc or gst), then you can use this device to play music too. If you want to use your own player with zicbee, just search the database and request some playlist (m3u) output !

Open your web browser, point http://localhost:9090/ and you should see some graphics.

To know all the commands, try zicdb help command. Note that there is a shortcut for zicdb serve, you can just type zicserve. Don't forget to run wasp help for all clients commands (most, in fact).

Help yourself

% wasp help
% zicdb help

Pattern/match command

Pattern is everywhere, used in www interface, in many shell commands (search, play, etc...).

Syntax summary:

field: value [ [or|and] field2: value2 ]...

for length, value may be preceded by < or >

if field name starts with a capital, the search is case-sensitive

Possible fields:

  • id (compact style)
  • genre
  • artist
  • album
  • title
  • track
  • score
  • tags
  • length
  • auto <special: auto-expand artists according to last.fm statistics)
  • pls <special: save/update a playlist>

Commented Examples

% wasp search artist: =shakira length: > 3*60

> songs from "shakira" and of more than 3 min

% wasp search artist: the rolling length: > 3*60 or artist: black

> songs with "the rolling" or "black" in artist name and of more than 3 min

% wasp search artist: shak length: > 3*60 and title: mo

> songs with "shak" in artist name and of more than 3 min and with "moon" on the title

% wasp search tags: jazz title: moon

> songs tagged "jazz" and with titles containing "moon"

% wasp search score: >2

> songs with a score higher than 2

% wasp search score: >2 score: <= 3 tags: rock length: <= 120

> a quite dumb search ;) (the selected songs will have a score of 3, less than 2 min and tagged as "rock")

Basic commands details

Most commands will read ::db_host and ::player_host variables (see set command).

Common to zicbee and wasp


List all available commands (with associated help if available)


Without argument, lists the variables If two arguments are passed, just set the value

List of "set" variables
fork ( yes,no )

tells if the server should fork or not

enable_history ( yes, no )

enable commands history in wasp

web_skin ( default )

skin name (only one now)

players* ( off,gst,mplayer,vlc )

player backend preference*

download_dir ( /tmp )

download directory for get command mainly

socket_timeout ( 30 )

sets the default socket timeout (increase the value if you have timeout problems)

default_search ( off, "any valid search pattern" )

sets the default pattern used in "play" command when no parameter is specified

allow_remote_admin ( yes,no )

allow usage of kill and stfu from any host

streaming_file ( /tmp/zsong )

temporary file used in player

history_size ( 50 )

size of commandline history |

custom_extensions* ( mpg, mp2 )

adds support for officially unsupported extensions to scan command*

player_host* ( localhost:9090 )

the host you want to play music on*

db_host ( localhost:9090 )

the host you want to take music from

notify ( yes,no )

add desktop notification support to advert song changes

default_port ( 9090 )

port used by default if not specififed

debug ( off,on )

enables debuging mode

autoshuffle ( yes,no )

automatically runs "shuffle" command when a playlist is fully loaded

loop ( yes,no )

runs player in loop, infinitely, if autoshuffle is enabled, then re- shuffle the playlist before each loop

{*} Multi values can be passed, using a coma (","), but NO SPACES. Note: "on" and "yes" are equivalent value, same for "off" and "no".

zicdb specific

Note that "command::argument1[=foo][:argument2...]" syntax is only supported by zicdb.


Runs a user-accessible www server on port 9090

pure: don't allow player functionality access

You can alternatively use the "zicserve" alias.

scan [directory|archive]...

Scan directories/archive for files and add them to the database

search[::format] "match command"

Search for songs, display results (output on stdout).

format: specifies the output format (for now: m3u or null or default)


List available Databases.


Erases the Database (every previous scan is lost!)

bundle "filename"

Create a bundle (compressed archive) of the database


Not a command by itself, used to specify active database (default: songs) Exemple:

% zicdb use lisa serve

> starts serving lisa's database

% zicdb use usb_drive reset

> destroy usb_drive database

% zicdb use ipod bundle ipod_database_backup.zdb

> backups the "ipod" database into "ipod_database_backup.zdb" file in current directory

WARNING: using more than one database will most probably lead to song conflicts and won't be usable consider this feature very experimental, use only if you know what you are doing.

NOTE: you can alternatively use the "ZDB" environment variable instead

wasp specific

get "match command"

Downloads the previous search result in download_dir

% wasp get artist: black
% zicdb search::out=m3u artist: black

show [number of items|slice]

Shows the playlist

  • show 4 will show the 4 elements from the current one
  • show 1:15 will show elements from 1 to 15
  • show :10 is equivalent to show 0:10
  • show 20: will show elements from 20 to end
  • show -5: syntax is not really supported but still "works" (shows the last 5 elements, but indexes are incorrect)


Display the whole playlist

play "match command"

Set playlist to specified request and start playing if previously stopped

match command: same as 'search' command with 2 more fields: pls: output playlist name playlist: input playlist name

  • "#" is the special name for the current playlist
  • names can be prefixed with > to append to playlist
  • or + to insert just after the current song
  • no prefix means replace

Not using any playlist field is equivalent to "pls: #"

Note a special sugar is provided when copy/paste'ing a zicbee uri.

% play http://myfriend.mydomain.com:9090/db/get/song.mp3?id=34g

Will be interpreted as play id: 34g pls: +# on myfriend.mydomain.com host.

More examples:
% wasp play artist: doors

> play the doors

% wasp play artist: bouchers pls: boucherie

> store in playlist "boucherie" songs with "bouchers" in artist

% wasp play artist: pigalle pls: +boucherie

> append to playlist "boucherie" songs with "pigalle" in artist

% wasp play playlist: boucherie

> play songs stored in playlist "boucherie"

% wasp play pls: sogood playlist: #

> save the current playlist to playlist "sogood"

search "match command"

Search for a patter, display results Results are also stored for commands like "get"

random "what"

Chooses a random thing (artist by default, can be "album" as well) then plays it


Prints the current playlist in m3u format

grep "arbitrary string"

Only shows playlist elements containing the specified string Result is stored for commands like "move" or "delete"

move "what" "where"

Moves song at position "what" to "where" If "where" is not given, defaults to the song next current one. "what" can be special keyword "grep", will move previously grep'ped songs


Display informations about player status


Shuffles the current playlist


Zap current song


Move backward in playlist


Tells if the given name matches with the current song


If you find any problem with installation, don't hesitate to post an Issue or contact me directly fdev31 AT gmail DOT com or fill the Bugtracker.