SYNOPSIS

vux [-bcdghjklnquvAFPRSVYZ] [-a file] [-e pattern] [-f value] [-i option] [-m option] [-o value] [-p file] [-r value] [-s file] [-t value] [-w option] [-x option] [-y file] [-z file] [-B value] [-C value] [-D value] [-G value] [-I value] [-M value] [-N value] [-O device] [-T value] [-U value] [-W option] [-X value]

DESCRIPTION

vux is a command-line ogg and mp3 utility that plays songs according to a rating system designed to keep track of user listening habits. By default, vux will give each song a percent chance of playing, based on where it lies on a bell curve of all ratings. Songs are picked at random, then played if they pass the percent chance. Ratings increase when you play complete songs and decrease when you skip them. The ratings scorelist is plain text. By default, a separate agelist is maintained to prevent repeats based on time since last played. See the MECHANICS section for details.

OPTIONS

When using vux for the first time, you must first run vux -x generate to generate an initial scorelist from a playlist. See the -x generate option for the playlist format. In most cases, find ~/music -type f > ~/.vux/playlist will work. Use -p playlist to override the default of ~/.vux/playlist.

-a file

Use file as the agelist instead of the default.

-b

Disable repeat updates when songs are played completely, when using -x weed or when using vuxctl next prev or replay.

-c

Disable rating checks.

-d

Disable rating updates when songs are played completely, when using -x weed.

-e pattern

Only play songs matching pattern. Mean and standard deviation are still calculated based on all ratings, but only those matching pattern are considered for playing. Globbing follows the rules for zsh filename generation; man zshexpn(1) for details. For example: vux -e '*Artist/Album*'. The entire pathname from the scorelist is used for matching.

-f value

Only used with -x force. Force ratings to value.

-g

Print ratings from -x ratings and -R in xgraph-friendly format. This also works with xplot. For example: vux -xr -g | xgraph would display a graph where x is rating and y is count. This option implies -q and disables -V.

-h

Print usage.

-i option

Select increase method for ratings. Default option is conservative.

c|conservative Increase less as the current rating gets closer to the maximum score.

a|accelerated

Increase more as the current rating gets closer to the middle rating.

i|inverse

Increase less as the current rating gets closer to the middle rating.

-j

Disable repeat checks.

-k

Disable repeat updates when songs are skipped.

-l

Disable rating updates when songs are skipped.

-m option

Select decrease method for ratings. Default option is conservative.

c|conservative Decrease less as the current rating gets closer to the minimum score.

a|accelerated

Decrease more as the current rating gets closer to the middle rating.

i|inverse

Decrease less as the current rating gets closer to the middle rating.

-n

Disable ogg and mp3 players. Useful for testing or batch rating with -Ve pattern.

-o value

Only used with -w middle. Use value as the end multiplier instead of the default.

-p file

Use file as playlist instead of the default. Only useful with -x generate, -x merge and -x weed.

-q

Minimize vux-generated output.

-r value

Only used with -w middle. Use value as the middle multiplier instead of the default.

-s file

Use file as the scorelist instead of the default.

-t value

Add value to the percent chance to play songs that are above or equal to the mean. When used with -W thresh, add value to threshold. Value may be positive or negative and may use vux variables and formulas. For example, all of the following are valid: vux -t 10 ; vux -t -std_dev ; vux -t '-0.5*std_dev'.

-u

Check for repeat before checking rating. Otherwise, ratings are checked first.

-v

Show version and exit.

-w option

Select rating method. Default option is bell.

b|bell Use the bell curve.

t|thresh

Use thresholds.

m|middle

Use distance from fixed middle.

-x option

Select action for vux to perform. Default option is play.

p|play Play music.

g|generate

Generate a new scorelist from playlist and exit. Playlist must have one pathname (the full path to each file, including the filename) per line. Spaces, symbols, etc. in the pathname are allowed as the line will be double-quoted in the scorelist. Each song will be given the default rating and scorelist will be backed-up and overwritten. This is only useful when generating a new scorelist.

m|merge

Similar to generate, but keeps the existing scores, adding only new songs from playlist and giving them the default rating.

w|weed

Remove all songs from the scorelist and agelist/countlist that do not appear in the playlist and exit. -W determines whether agelist or countlist is updated. -d and -b disable pruning from the scorelist and agelist/countlist respectively.

r|ratings

Show rating count, mean, standard deviation and other statistics, depending on the rating method used, then exit.

f|force

Force ratings of songs selected with -e pattern. Without additional arguments, this option will cause all ratings of selected songs to be increased once using the current increase method. With -F, all ratings of selected songs will be decreased once using the current decrease method. With -f value, all ratings of selected songs will be replaced with value.

-y file

Use file as the missing file log instead of the default.

-z file

Only used with -W count. Use file as the countlist instead of the default.

-A

Only used with -W age. Disable saving the agelist. Otherwise, vux saves the agelist after every 30 songs played and on SIGINT.

-B value

Only used with -w middle. Use bend factor value instead of the default.

-C value

Only used with -w thresh. Use random reprieve factor value instead of the default.

-D value

Use decrease factor value instead of the default.

-F

Behave as if songs were skipped when using -n or -x force. The default is to behave as if songs were played completely.

-G value

Only used with -W age. Use value method to prevent runaway age checking in case many songs are below the minimum age. When searching for a song to play, value represents the number of times an age check will fail before vux will ignore age. Also valid are: total or t for total number of songs, sqrt or s for square root of the total number of songs, or -1 for no method.

-I value

Use increase factor value instead of the default.

-M value

Only used with -W age. Use minimum age value instead of the default. A valid value is a number followed by d for days, h for hours, m for minutes or s for seconds. For example, 7d, 3h, 20m, and 45s are valid. The status line will display the time since plast played in the time units specified here.

-N value

Only used with -W count. Use count value instead of the default. This is the number of times a song will fail to be chosen after being chosen successfully.

-O device

Use device as the sound device checked before running a player. Use /dev/null as the device to disable checking. Default is /dev/dsp.

-P

Only useful with -W age. Songs with no age value will be played without a rating check. This option implies -u.

-R

Show rating count, mean, standard deviation and other statistics, depending on the rating method used. This is the same as -x ratings, but is displayed after any other processing.

-S

Disable saving the scorelist. Otherwise, vux saves the scorelist after every 30 songs played and on SIGINT.

-T value

Subtract value from percent chance to play songs that are below the mean. With -w thresh, add value to reprieve threshold. See -t.

-U value

Use default rating value instead of the default. This is only useful with -x generate and -x merge.

-V

Add a "-v" to cp and rm.

-W option

Select repeat-checking method. Default option is age.

a|age Test repeats by age.

c|count

Test repeats by counting down.

-X value

Use maximum score value instead of the default.

-Y

Disable using the missing log. Otherwise, songs that are not readable (unless beginning with http) will be appended to the missing log.

-Z

Only used with -W count. Disable saving the countlist. Otherwise, vux saves the countlist after every 30 songs played and on SIGINT.

CONTROL

Control of vux is handled by signals, usually through shell or window manager key bindings such as:

  kill -HUP `cat ~/.vux/vux.pid`

  kill -INT `cat ~/.vux/vux.pid`

For a wider range of control, the vuxctl program is available. See vuxctl(1) for details.

Signals

HUP vux

skip current song and lower its rating

INT vux

exit vux, end current song without changing its rating and save current scorelist

INT player

skip current song but increase the rating (only works when player exits 0 after receiving SIGINT --- defaults for player are ogg123 and mpg321, which do)

DISPLAY

When playing songs, vux displays the following:

decision line

While vux is searching for a song to play at random, the following characters are printed:

x

Only used with -w thresh. Chosen song was below the reprieve threshold.

.

Chosen song failed its percent chance to be played. With -w thresh, chosen song was below the threshold, above the reprieve threshold and failed the random reprieve chance.

!

Only used with -w thresh. Chosen song was below the threshold, above the reprieve threshold and passed the random reprieve chance. This song will be played unless the ! is followed by a :.

+

Chosen song succeeded in its percent chance. With -w thresh, chosen song was above the threshold. This song will be played unless the + is followed by a :.

:

Chosen song failed the repeat test.

~

Only used with -W age. Chosen song did not meet the minimum age, but the age bypass was reached and the song will be played anyway.

-

Only used with -P. Chosen song has no age value, the rating check will be skipped and the song will be played.

status line with -w bell and -W age

current rating/percent chance/mean/standard deviation/age

status line with -w thresh and -W age

current rating/threshold/mean/reprieve threshold/age

status line with -w bell and -W count

current rating/percent chance/mean/standard deviation

status line with -w thresh and -W count

current rating/threshold/mean/reprieve threshold

path to song file

Path to song file up to the last forward slash.

filename

Filename of song.

player output

Normal player output.

new rating

If rating updates are enabled, the new rating is displayed after the song ends.

Output from vuxctl commands are displayed as they occur.

MECHANICS

vux uses simple algorithms to decide what song to play and to determine how much to change the rating. Two things decide what songs will be played: the rating method and the repeat-avoidance method. By default, vux uses the bell curve rating method and the age repeat-avoidance method.

Choosing a Song by Rating with -w bell

Upon choosing a song at random, vux calculates the mean and standard deviation for all ratings in the scorelist. vux then applies a simplified bell curve model to the song's rating, to determine its percent chance of playing. As the rating approaches +3 standard deviations from the mean, the chance of playing approaches 100%. As the rating approaches -3 standard deviations from the mean, the chance of playing aproaches 0%. If the song fails its percent chance, the song is not played and another is picked at random and the process repeats.

Choosing a Song by Rating with -w thresh

vux uses 2 floating thresholds, the threshold and the reprieve threshold:

         threshold = ( mean + standard deviation )
reprieve threshold = ( mean - standard deviation )

These values are calculated before choosing a song and divide the scorelist into three sections:

rating >= threshold

Always play if picked at random.

rating < threshold and >= reprieve threshold

1 in 10 (default) chance of playing if picked at random.

rating < reprieve threshold

Never play if picked at random.

If the song does not qualify to be played, another song is picked at random and the process repeats.

Choosing a Song by Rating with -w middle

This is the simplest rating method. Rating probabilities are determined by these variables (defaults shown):

      max_score=100

      min_score=0

      bend_factor=10

      end_mult=1.5

      middle_mult=1.1

vux takes the song's rating and uses that as its probability of playing (if max_score and min_score are not 100 and 0 respectively, vux first extrapolates it into a 0-100 scale.) This probability is modifed by multiplying it either by end_mult or middle_mult. middle_mult is used for ratings that are between middle rating + bend_factor and middle rating - bend_factor.

Avoiding repeats with -W age

After a song is played, vux associates a timestamp with the song. When the song is chosen again, the timestamp is subtracted from the current time and compared to minimum age. If the result is not greater that minimum age, the song is not played.

Avoiding repeats with -W count

After a song is played, vux associates a number with the song. This number is set with -N and defaults to 10. When the song is chosen again, the number is decremented and the song is not played. Once the number reaches 0, the song will be available to play again.

Changing Ratings

Rating changes are controlled by these variables (defaults shown):

      max_score=100

      min_score=0
decrease_factor=10
increase_factor=10

When a song is skipped, its rating changes according to this formula:

decrease = integer of(current_rating / - decrease_factor)

With -m accelerated, the following formula is used instead:

x = current_rating - min_score
y = max_score - current_rating
decrease = integer of(maximum of(1,(minimum of(x,y)/2)) * -1

With -m inverse, the following formula is used instead:

x = max_score - min_score
y = absolute value of ( current_rating - x )
decrease = integer of( y / decrease_factor ) - 1 ) * -1

When a song is played all the way through (or the player is sent a SIGINT), its rating changes according to this formula:

increase = integer of((max_score - current_rating) / increase_factor)

With -m accelerated, the following formula is used instead:

x = current_rating - min_score
y = max_score - current_rating
increase = integer of(maximum of(1,(minimum of(x,y)/2))

With -m inverse, the following formula is used instead:

x = max_score - min_score
y = absolute value of ( current_rating - x )
increase = integer of( y / increase_factor ) + 1 )

DIAGNOSTICS

vux will exit 0 if there are no errors. Otherwise, the following exit codes are used:

1

Usage error.

2

Unable to create vux working directory.

3

Scorelist lockfile already exists.

4

Unable to load scorelist.

5

No matching songs found with -e.

6

Unable to open socket.

EXAMPLES

vux -x generate

Generate a new scorelist from $HOME/.vux/playlist and exit.

vux -x ratings

Show song ratings and exit.

vux -x merge -RU 60 -p $HOME/.vux/newsongs

Merge $HOME/.vux/newsongs with $HOME/.vux/scorelist, adding new songs with a rating of 60, show ratings after merging and exit.

vux -cdS

Play songs, but do not choose songs based on rating, update ratings or save the scorelist.

vux -jbA

Play songs, but do not avoid repeats based on age, update ages or save the agelist.

vux -W count -jbC

Play songs, but do not avoid repeats based on count, update counts or save the countlist.

vux -M 4d -G -1

Do not repeat songs for 4 days, display ages in days and never bypass age checking.

vux -W count -N 20

Do not repeat songs for 20 attempts.

vux -k

Do not update age on skipped songs.

vux -t 10 -T 20

Add 10% to the percent chance to play songs above the mean and subtract 20% from the percent chance to play songs below the mean.

vux -w thresh -t 10 -T -20

Use the threshold rating method, add 10 to threshold and subtract 20 from reprieve threshold.

vux -w thresh -T std_dev

Use threshold rating method, add current standard deviation value of all ratings to reprieve threshold, limiting song choice to mean and above.

vux -dbnSAV

Do not change ratings or ages, do not play music and do not save scorelist or agelist. This will show what vux would do without actually playing anything.

vux -e '*Artist/Album*'

Only consider songs matching *Artist/Album*.

vux -e '*Artist/(Album1|Album2)*'

Only consider songs matching *Artist/Album1* or *Artist/Album2*.

vux -cje '(#i)*whale*'

Play songs with whale in the pathname, ignoring case, rating and age.

vux -cjnVFe '(#i)*purse*'

Choose songs with purse in the pathname, ignoring case, rating and age. Do not actually play the songs, but display the song name and lower its rating. This will continue choosing songs from the selection and lowering ratings indefinitely.

vux -x force -e '*Artist*'

Increase the rating of each song matching *Artist* once, using the conservative increase method, then exit.

vux -x force -e '*Artist*' -F

Decrease the rating of each song matching *Artist* once, using the conservative decrease method, then exit.

vux -x force -e '*Artist*' -f 100

Set the rating of each song matching *Artist* to 100, then exit.

FILES

/etc/vuxrc

system configuration file

$HOME/.vux/vuxrc

user configuration file

$HOME/.vux/playlist

default playlist to generate, merge or weed scorefiles from --- this is never modified by vux

$HOME/.vux/scorelist

default scorelist

$HOME/.vux/agelist

default agelist

$HOME/.vux/countlist

default countlist

$HOME/.vux/missing

default missing file log

$HOME/.vux/*.bak

default backup file; made before saving

$HOME/.vux/*.lock

default lockfile preventing a file save or load while saving

$HOME/.vux/vux.pid

file containing PID of any vux process using -x play

$HOME/.vux/ctl

vux control socket

AUTHOR

This manual page was written by Brian Nelson <[email protected]>, for the Debian GNU/Linux system (but may be used by others).