--- name: "vux" section: "1" platform: "linux" package: "vux" version: "0.4.9" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/vux" --- # vux(1) a rating-based, random ogg and mp3 player ## NAME vux – a rating-based, random ogg and mp3 player ## 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)](/zshexpn/1.md) 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)](/vuxctl/1.md)** 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. ## BUGS Use the Debian Bug Tracking System for reporting bugs and making suggestions. ## SEE ALSO **[zshexpn(1)](/zshexpn/1.md), [vuxctl(1)](/vuxctl/1.md)** ## 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 \, for the Debian GNU/Linux system (but may be used by others).