 |
|
| |
VITUNES(1) |
FreeBSD General Commands Manual |
VITUNES(1) |
vitunes —
A curses media indexer and player for vi-users
vitunes |
[ -c
command ]
[-d
database-file ]
[-e
command [ argument
... ] ] [-f
config-file ]
[-m
media-backend ]
[-p
playlist-dir ] |
vitunes is a curses-based music player and
playlist manager for *nix whose goals are a minimalistic appearance, strong
vi-like bindings, and quick playlist creation/management.
It is not intended to be a feature-rich media player, but rather a quick,
vi-like media indexer and playlist manager that also happens to be able to
play the media it indexes (via
mplayer(1)
).
vitunes accepts the following command line
options:
-c
command
- Execute the specified command in the currently running
vitunes instance, and exit. This is
useful for controlling vitunes from
other windows or scripts.
The commands that may be specified are both those named in the
RUN-TIME COMMANDS
section below and keybindings specified by their keybinding action name,
listed in the
KEYBINDING ACTIONS
section below.
To execute multiple commands, use this option repeatedly as
$ vitunes -c command1 -c command2
...
For example, to have the currently running
vitunes load and play a playlist, one
could issue:
$ vitunes -c ‘playlist
SomePlaylist’ -c media_play
Note that for this to work, when vitunes
starts up it attempts to create a socket at
/tmp/.vitunes that are used by this
option to communicate with the original instance. If this socket cannot be
created for any reason, this option will not work.
-d
database-file
- Specifies the database containing all known media files and their meta
information that
vitunes should use. If
you're using this option in conjunction with an e-command, this option
must be specified before the e-command.
The default location is
~/.vitunes/vitunes.db.
-e
command
options
- Execute one of the available e-commands to manipulate the database that
vitunes uses. See the section below
titled E-COMMANDS for more
information.
-f
config-file
- Specifies the path of the configuration file
vitunes should load. See the section
below titled
CONFIGURATION FILE
for information on what the configuration may contain.
The default location is
~/.vitunes/vitunes.conf.
-m
media-backend
- Specify the media backend to use for playback. The current list of
supported media backends are:
mplayer
- Uses a
fork(2)
/
execvp(3)
'd instance of
mplayer(1)
for all playback. Note that the mplayer binary
must be in your
PATH environment variable.
Currently only mplayer is supported.
-p
playlist-dir
- Specifies the directory containing all of the playlists
vitunes will load and use. Any new
playlists created while running vitunes
will be created here.
The default location is
~/.vitunes/playlists/.
vitunes works by maintaining a database of
tagged media files. The database must be created
and populated before vitunes can be run
normally.
After that, files can be added, modified, or removed from the database, and on
the next invocation, vitunes will see the
changes (additionally, the database can be re-loaded at runtime).
See the E-COMMANDS section below
for more information on database management. To get started quickly, simply do
the following:
- Create initial empty database with
$ vitunes -e init
- Add files to your database with
$ vitunes -e add ~/music/
/path/to/more/music/
- Then just start normally with
$ vitunes
When run normally, the default display will show the following 4 windows:
- player
- This window occupies the top row of the display and contains information
about the currently playing song (if any) and the current play-mode.
- command/status
- This window occupies the bottom row of the display. It behaves very
similar to the command/status window in
vi(1).
- library
- This window occupies the left-side of the screen and shows each playlist,
in addition to the library and filter-buffer. The filter buffer is where
the results of every :
filter
... command are temporarily stored.
Playlists with unsaved changes appear bold and have their name preceded with
a '+'.
- playlist
- This window is to the right of the library window and occupies most of the
display. It shows the contents of whichever playlist has currently been
selected in the library window.
The following is only a partial listing keybindings, but are the most frequently
used.
Enter
- Load the selected playlist for viewing or begin playback of the selected
file.
Tab
- Toggle focus between the library and playlist windows.
z
- Pause playback.
s
- Stop playback.
f/b
- Seek forwards/backwards 10 seconds.
F/B
- Seek forwards/backwards 1 minute.
m
- In the playlist window, show/hide information for the current file.
See the KEYBINDING
ACTIONS section for a complete listing.
Below is a brief summary of each e-command available in
vitunes . More detailed usage information
and examples for each can be obtained by issuing:
$ vitunes -e help
command-name
vitunes
-e
init
- Create the necessary database file and playlist directory used by
vitunes . This command only needs to be
run once, when vitunes is first run. If
either of these already exist, they remain unchanged.
vitunes
-e add
path1
[path2 ... ]
- This command takes any number of files/directories as parameters. Each
file is scanned for meta-information and if found, added to the database.
Directories are search recursively.
TagLib(3)
is used for all meta-extraction, which includes the following fields:
album, artist, comment, play-length, title, track number, and year.
vitunes
-e
addurl
url
- This command is used to add non-files (things like URL's for Internet
radio stations) to the database, where the meta-information cannot be
determined automatically. It can also be used to update the meta-info of
an existing URL in the database.
After executing, you are prompted to enter all of your own information.
vitunes
-e
check
[-rsd ]
file1
[file2 ... ]
- Scan the files specified and display their meta-information as present in
the files themselves or in the
vitunes
database. This is useful for checking if a file is in the database.
vitunes
-e
flush
[-t
time-format ]
- Dump the contents of the database to stdout in an easy-to-parse format,
optionally with the specified
strftime(3)
compatible format for times.
vitunes
-e
help
command
- Display detailed usage information and examples for the e-command
specified by command.
vitunes
-e rm
[-f ]
file/url
- Remove a file/URL from the database.
vitunes
-e
rmfile
[-f ]
file/url
- Alias for the "rm" e-command.
vitunes
-e tag
[options ] file1
[file2 ... ]
- Add/modify the meta-information tags of raw files. There are many options
to this e-command. See the help page for more information:
$ vitunes -e help
tag
vitunes
-e
update
[-s ]
- Load the existing database and check each file to see if its
meta-information has been updated, or if the file has been removed. The
database is updated accordingly.
Below is a listing of all run-time commands supported by
vitunes .
All commands are entered by typing ':' followed by the command name and any
parameters (just like in
vi(1)
).
Note that abbreviations are also supported. That is, entering any non-ambiguous
abbreviation of a command name will also execute the command.
- :
bind
action
keycode
- This will bind the action specified by
action to the keycode specified by
keycode. After this command is issued,
entering the inputting the specified
keycode will result in firing the
specified action.
See the section
SPECIFYING
KEYCODES for details on how to specify
keycode, and section
KEYBINDING ACTIONS
for a listing of all actions
vitunes
supports.
- :
color
item =fg,bg
- Change the color of the given
item to
fg colored text on a
bg colored background.
Available values for item are:
- Item Name
- Description
bars
- The bars dividing the various windows.
player
- The player window.
status
- The status window.
library
- The library window.
playlist
- The playlist window.
errors
- Error messages in the status window.
messages
- Informational messages in the status window.
tildas-library
- The tildas in empty rows of the library window.
tildas-playlist
- The tildas in empty rows of the playlist window.
playing-library
- Currently playing playlist in the library window.
playing-playlist
- Currently playing file in the playlist window.
current-inactive
- Current row in the inactive window.
artist
- The artist column in the playlist window.
album
- The album column in the playlist window.
title
- The title column in the playlist window.
track
- The track column in the playlist window.
year
- The year column in the playlist window.
genre
- The genre column in the playlist window.
- The comment column in the playlist window.
length
- The play-length column in the playlist window.
Available colors for fg and
bg are: white, black, red, green, yellow,
blue, magenta, cyan, and default. The color default is whatever the
terminal uses as the default foreground or background color.
- :
display
(reset |
show |
display-description)
- The display command is used to change which columns are displayed in the
playlist window, their order, their width, and their alignment.
The format of display-description is a
comma separated list of:
“[
- ]field.size”.
Valid values for field are: album, artist,
comment, genre, length, title, track, and year. The
size field indicates the number of
columns. If field is preceded with a
- the field will be right-aligned. As an
example, the command:
:display
title.10,artist.20,-track.4
would only show the title, artist, and track fields, in that order, where
the title field is 10 columns wide, the artist field is 20 columns wide,
and the track field is 4 columns wide and right-aligned.
The default display can be restored with:
:display
reset
The current display description can be seen with:
:display
show
- :
filter [! ]
token
[token2 ... ]
- The filter command is used to filter out all songs from the currently
viewed playlist that do not match (or do match) the provided list of
tokens. A song matches the list of tokens if each token appears somewhere
in the song's meta-information or filename.
If “:
filter ” is used, all
records not matching the list of tokens are removed from the current
playlist. If “:filter! ”
is used, all records that do match the list of tokens are removed from the
current playlist.
The list of tokens is simply any list of strings, each possibly preceded
with an exclamation point. If a token is preceded with an exclamation
point, it will only match a song if it does not appear anywhere in the
song's meta-information or filename.
For example, the following:
:filter nine
nails
would match all songs that contained both "nine" and
"nails", and remove all other songs from the current playlist.
However,
:filter! nine
nails
would remove all songs that DO contain both "nine" and
"nails."
The query:
:filter nine
!nails
would match all songs that contain "nine" and NOT
"nails". All other songs would be removed from the current
playlist.
- :
mode
(linear |
loop |
random )
- Set the current playmode to one of the three available options. The
options are:
linear
- Songs in a playlist are played in the order they appear until the end
is reached.
loop
- Like linear, but when the end of the playlist is reached, playback
continues at the beginning of the playlist.
random
- Songs are chosen at random from the playlist.
- :
new
[name ]
- Create a new, empty playlist. If name is
provided, the new playlist will be named accordingly unless a playlist
with that name already exists. If no name is provided, the default is
"untitled".
- :
playlist
name
- Load the playlist named by name in the
playlist window.
- :
q [! ]
- Quit
vitunes . If there are playlists
with unsaved changes, then you are notified of this and prevented from
quitting. You can forcefully quit by using
:q !, and any unsaved changes to any
playlists will be lost.
Note that playlists with unsaved changes appear bold in the library
window.
- :
reload
(db |
conf )
- The reload command is used to reload either the database or configuration
file while
vitunes is running. Handy if
you update your database using an e-command while also running
vitunes .
- :
set
property =value
- The set command is used to set various properties within vitunes. For
properties that accept a value of bool,
valid values are 'true' and 'false'.
The following properties are available:
lhide =bool
- If set to true, the library window will be hidden (disappear) when it
does not have focus.
lwidth =number
- Set the width of the library window to
number columns wide. Note that the
number provided must be greater than 0 and less than the width of the
terminal.
match-fname =bool
- When searching or filtering a playlist, normally the filenames are
also included in the matching algorithm. This can sometimes be
undesirable, particularly if, for example, all of your music/media
reside in a directory named "media" and you're trying to
search for a file with the word "media" in the title.
To disable this behavior, set match-fnames to false.
save-sorts =bool
- Most operations that change a playlist (such as paste/cut) set the
'needs-saving' flag on the playlist, such that you are prompted on
exiting vitunes that there is a playlist with unsaved changes. By
default, sorting a playlist does not do this.
To change this behavior, and be prompted to save sorts on exit, set this
option to true.
- :
sort
sort-description
- Sort the currently viewing playlist using the provided
sort-description, which is a comma
separated list of:
“[
- ]field”,
specifying which fields to sort by and if they should be sorted ascending
or descending.
Valid values for field are: album, artist,
comment, genre, length, title, track, and year. Each field is sorted
ascending by default, unless the field is preceeded with the dash
-, in which case that field is sorted
descending.
As an example, the following command:
:sort artist,-album,title
would sort all records in the current playlist by artist (ascending) first,
then album-name (descending), then title (ascending).
Note that while most operations on playlists set the
"needs-saving" flag (so you are prompted when quiting
vitunes that the playlist has unsaved
changes), sorting a playlist does not do this. This is intentional. If you
wish this behavior to be changed, see the "save-sorts" option
for the set command.
- :
toggle
register
command-list
- This command will associate a list of commands specified by
command-list to register
register. Once set, the list of commands
can be quickly toggled through using the
toggle_forward and
toggle_backward keybindings (which
default to t and
T , respectively).
Toggle-lists can be useful to quickly alternate through, for example,
various sorting or display schemes that the user may prefer.
register is any single lower-case letter (a
- z) or uppercase letter (A - Z).
command-list is any list of valid
commands listed here, each separated by a backslash character '/'.
As an example, the following would allow one to quickly toggle through
various sorting schemes:
toggle s sort artist,-year,track / sort
artist,album,track / sort -year
Once issued, the three individual sorts specified above can be toggled using
the s register. With the default
keybindings this would be done using either
ts (to toggle forward through the list)
or Ts (to toggle backward through the
list).
- :
unbind
(* |
action
action |
key
keycode)
- This command is used to remove existing keybindings. It has three forms.
The first is simply:
unbind *
which will remove all existing keybindings. This is handy in a configuration
file where you may want to define all custom keybindings. Issuing this at
runtime will leave you with an instance of
vitunes that will not respond to any
keybdings!
The second form is used to unbind actions:
unbind action
action
This will remove any keybindings for the action specified by
action.
The third form is used to unbind keys:
unbind key
keycode
This will remove any action currently bound to the key specified by
keycode.
See the section
SPECIFYING
KEYCODES for details on how to specify
keycode, and section
KEYBINDING ACTIONS
for a listing of all actions vitunes
supports.
- :
w [! ]
[name ]
- Save the currently viewing playlist. If a
name is provided, then the playlist will
be saved with this new name. If, however, a playlist already exists with
that name, then you will be prevented from saving with that name unless
'!' is provided, in which case the existing playlist with that name will
be deleted.
This section describes how to specify keycodes used in both the
: bind and
: unbind commands.
Keycodes are specified in the following fashion:
[Control ]
(key |
SpecialKey)
Here, key is used to specify the actual,
printable character entered which is case-sensitive (e.g. 'j', 'p', 'P'), and
SpecialKey is used to specify various
non-printable characters (such as the Page-Up key).
If the string “Control” is also specified, then the keycode only
applies when the control key is pressed in conjunction with the
key or
SpecialKey.
Although key is case-sensitive ('p' and 'P'
are treated differently), both SpecialKey and
“Control” are case-insensitive.
The currently supported list of non-printable characters available for
SpecialKey are:
Value |
Description |
PageUp |
The page-up key. |
PageDown |
The page-down key. |
Up |
The up-arrow key. |
Down |
The down-arrow key. |
Left |
The left-arrow key. |
Right |
The right-arrow key. |
Backspace |
The backspace key. |
Enter |
The enter key. |
Space |
The space key. |
Tab |
The tab key. |
Some examples of using keycodes and the : bind
run-time command are:
bind paste_after p
bind paste_before P
bind scroll_up_halfpage Control u
bind scroll_down_halfpage Control d
The current list of available actions that keys may be bound to is the
following. For each action, the default keys bound to them are also listed.
- Action Name
- Description
scroll_up
- Scroll the current row in the current window up by one line.
DEFAULT BINDINGS: k, -, Up
scroll_down
- Scroll the current row in the current window down by one line.
DEFAULT BINDINGS: j, Down
scroll_up_page
- Scroll the current window up by one line.
DEFAULT BINDINGS: Control y
scroll_down_page
- Scroll the current window down by one line.
DEFAULT BINDINGS: Control e
scroll_up_halfpage
- Scroll the current window up one half-page.
DEFAULT BINDINGS: Control u
scroll_down_halfpage
- Scroll the current window down one half-page.
DEFAULT BINDINGS: Control d
scroll_up_wholepage
- Scroll the current window up one whole page.
DEFAULT BINDINGS: Control b, PageUp
scroll_down_wholepage
- Scroll the current window down one whole page.
DEFAULT BINDINGS: Control f,
PageDown
scroll_left
- Scroll the current window to the left one column.
DEFAULT BINDINGS: h, Left, Backspace
scroll_right
- Scroll the current window to the right one column.
DEFAULT BINDINGS: l, Right, Space
scroll_leftmost
- Scroll the current window to the left as far as possible.
DEFAULT BINDINGS: ^, 0, |
scroll_rightmost
- Scroll the current window to the right as far as possible.
DEFAULT BINDINGS: $
jumpto_screen_top
- Move the current line to the first line in the current window.
DEFAULT BINDINGS: H
jumpto_screen_middle
- Move the current line to the middle line in the current window.
DEFAULT BINDINGS: M
jumpto_screen_bottom
- Move the current line to the bottom line in the current window.
DEFAULT BINDINGS: L
jumpto_line
- Jump to either a specified line (if a global input number is present) or
to the last line in the current window's buffer.
DEFAULT BINDINGS: G
jumpto_percent
- Using the global input number N, jump to the line N% the way through the
current window's buffer.
DEFAULT BINDINGS: %
go
- Go to a specific location within the current window. This is planned to be
similar to
vim(1)
's use of the 'g' keybinding, with multiple suffixes. For now, only 'gg'
is supported, and this takes you to the first line in the current window's
buffer.
DEFAULT BINDINGS: g
search_forward
- Begin a search for the entered string searching forward in the current
window. The current row will be updated to the next matching row.
DEFAULT BINDINGS: /
search_backward
- Begin a search for the entered string searching backwards in the current
The current row will be updated to the next matching row. window.
DEFAULT BINDINGS: ?
find_next_forward
- Using the previous search-string, search in the same direction as the
search was input for the next matching row.
DEFAULT BINDINGS: n
find_next_backward
- Using the previous search-string, search in the opposite direction as the
search was input for the next matching row.
DEFAULT BINDINGS: N
cut
- Remove the following N lines from the current window, placing them in the
copy buffer, where N is the global input number. Note that if the library
window is active, only one row (playlist) can be cut/deleted at a time,
and that this action cannot be undone.
DEFAULT BINDINGS: d
visual
- Begin visual mode. This is only available in the playlist window, and once
begun, only keybindings that move the cursor within the current window are
allowed. Visual mode is exited when either a yank or delete operation has
been performed, or when the Escape key is pressed.
DEFAULT BINDINGS: v, V
yank
- Copy the following N lines from the current window into the copy buffer,
where N is the global input number. This action cannot be used in the
library window.
DEFAULT BINDINGS: y
paste_after
- Paste the contents of the copy buffer after the current row in the
playlist window. This action cannot be used in the library window.
DEFAULT BINDINGS: p
paste_before
- Paste the contents of the copy buffer before the current row in the
playlist window. This action cannot be used in the library window.
DEFAULT BINDINGS: P
undo
- Undo the previous action on the currently viewed playlist. This action
cannot be used in the library window.
DEFAULT BINDINGS: u
redo
- Redo the previously undone action on the currently viewed playlist. This
action cannot be used in the library window.
DEFAULT BINDINGS: Control r
quit
- Exit
vitunes . If there are unsaved
changes in any playlists you will be prevented from exiting until you
either save those changes or issue a ":q!" command.
DEFAULT BINDINGS: Control c, Control
/
redraw
- Clear and re-draw the entire display.
DEFAULT BINDINGS: Control l
command_mode
- Enter command-mode, where the commands listed in the
RUN-TIME COMMANDS
section may be issued.
DEFAULT BINDINGS: :
shell
- Enter a command to be executed outsite of
vitunes and in the current shell
environment. The output of the execution is shown before control and the
display returns to vitunes .
DEFAULT BINDINGS: !
switch_windows
- Toggle focus between the library and playlist windows.
DEFAULT BINDINGS: Tab
show_file_info
- Show the file information (including meta-information) for the current
row/file in the playlist window. This action does not work in the library
window.
DEFAULT BINDINGS: m
load_playlist
- Load the playlist specified by the current row in the library window.
DEFAULT BINDINGS: Enter
media_play
- Begin playing the file specified by the current row in the playlist
window.
DEFAULT BINDINGS: Enter
media_pause
- Pause playback of any playing media.
DEFAULT BINDINGS: z
media_stop
- Stop all playback of any playing media.
DEFAULT BINDINGS: s
seek_forward_seconds
- Seek forwards 10 seconds in any playing media.
DEFAULT BINDINGS: f, ]
seek_backward_seconds
- Seek backwards 10 seconds in any playing media.
DEFAULT BINDINGS: b, [
seek_forward_minutes
- Seek forwards 1 minute in any playing media.
DEFAULT BINDINGS: F, }
seek_backward_minutes
- Seek backwards 1 minute in any playing media.
DEFAULT BINDINGS: B, {
media_next
- Play the next song in the playlist.
DEFAULT BINDINGS: )
media_prev
- Play the previous song in the playlist.
DEFAULT BINDINGS: (
volume_decrease
- Decrease the volume.
DEFAULT BINDINGS: <
volume_increase
- Increase the volume.
DEFAULT BINDINGS: >
toggle_forward
- Execute the next command from the toggle list specified by the provided
register.
DEFAULT BINDINGS: t
toggle_backward
- Execute the previous command from the toggle list specified by the
provided register.
DEFAULT BINDINGS: T
Some examples of using the above actions and keycodes to define the default
keybdings are:
bind paste_after p
bind paste_before P
bind scroll_up_halfpage Control u
bind scroll_down_halfpage Control d
The configuration file loaded by vitunes is
relatively straight-forward. Each line may be one of the following:
- A comment, which starts with a '#'.
- An empty line.
- One of the commands from the
RUN-TIME COMMANDS
section above.
That's it. As such, review the list of commands above.
An example configuration file that would setup some hideous DOS-like colors is:
# setup colors
color bars=white,blue
color player=yellow,blue
color library=green,blue
color playlist=white,blue
color status=red,blue
# format for playlist window
display artist.20,album.20,title.20,track.4,year.4
# show most recent work of an artist first in library window
sort artist,-year
# make library window 20 columns wide and hide when not active
set lwidth=20
set lhide=true
- ~/.vitunes/vitunes.conf
- Default configuration file.
- ~/.vitunes/vitunes.db
- Default database file.
- ~/.vitunes/playlists/
- Default playlist directory.
- /tmp/.vitunes
- Default location for the socket created on start-up that can be used to
control
vitunes .
- /usr/local/bin/mplayer
- Default path to the
mplayer(1)
binary.
mplayer(1),
realpath(3),
strftime(3),
vi(1).
More information about TagLib can be found on the TagLib website:
http://developer.kde.org/~wheeler/taglib.html
The vitunes website has additional
information, such as a list of frequently asked questions, a mailing list, and
up-to-date bug information.
http://www.vitunes.org
vitunes was written by
Ryan Flannery
< ryan.flannery@gmail.com>.
None known.
If you happen to find any, please send a detailed description to me at
ryan.flannery@gmail.com.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|