The zbucium Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The zbucium Reference Manual

This is the zbucium Reference Manual, version 0.1, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:59:25 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

zbucium

last.fm music player with lyrics and scrobble support, among other things.

This is a Common Lisp library that can be used to build a more interactive music player on top, like the zbucium-stump player for the StumpWM window manager for which this library was created in the first place. But it can also be used as such. It depends on the lastfm, youtube and lyrics libraries by the same author. The songs are played from youtube with the mpv player, in the background, with input from last.fm.

Installation

Install lastfm, youtube and the lyrics Common Lisp libraries from the same author. These are not yet in the quicklisp database but were developed specifically for this project. Since they might be useful in other context, they were written as libraries.

# clone to local-projects for quickload access
git clone https://github.com/mihaiolteanu/zbucium ~/quicklisp/local-projects/zbucium
; Register the new project
(ql:register-local-projects)

Usage

You tell zbucium what to play and it will open an audio-only mpv instance in the background and play it. You can play single songs, single albums and, more interestingly, discover new music by playing similar artists or top songs from a given genre. You chose how many artists and songs to take into consideration. Fewer, for topsongs and hits, many for a more eclectic experience.

(play-song "anathema" "one last goodbye")

The lyrics of the current playing song can also be retrieved.

(song-lyrics)
    => "How I needed you
        How I grieve now you're gone
        In my dreams I see you ...."

Even if you don't request the lyrics, they are requested and saved by default.

All the other functionality you would expect from a player are now available, like play/pause, seek, stop or request the opening of the youtube page in your default browser.

But you can also feed the player an infinite stream of songs, thanks to the generators provided by the lastfm library. This will play the best 30 songs from anathema (based on the last.fm recomendations), at random, until yout stop it or until you chose to play something else.

(play-artist "anathema" 30 T)

Or play random songs from random artists similar to the given artist. You have to select how many artists to consider and how many songs for each of those artists to take into consideration. The lower the value, the better the chances to play more similar artists and more top songs/hits for thos similar artists. The higher the values, the higher the chances to discover hidden gems.

; Play the best three matching artists and play from the best ten songs for
; those matching artists
(play-artist-similar "anathema" 3 10)
(what-is-playing)
    => ("Riverside" "Second Life Syndrome")
    
(next-song)
(what-is-playing)
    => ("Katatonia" "Leaders")
    
(stop)

API

play-song artist song

Play a single song and then quit.

play-artist artist nsongs random

Play the best nsongs, as reported by last.fm, for the given artist, in
random order or one after another. 

play-album artist album

Play a single album from the given artist.

play-tag tag nsongs random

Play the best songs for this tag (genre, usually). There is a similar
`play-tag-similar` function but the results are different.

play-user-songs username nsongs random

Play the first nsongs from the list of user loved songs. Can be played at
random or one after another.

play-my-loved-songs nsongs random

Play from the list of my loved songs. The username in this case is base on
the lastfm configuration.

play-artist-similar artist nartists nsongs

Picks a random artist from the top nartists that last.fm says are the most
similar to this artist. After that, pick a random song from the first best
nsongs of the selected artist and play it. 

play-tag-similar tag nartists nsongs

Picks a random artist from the top nartists that last.fm says are the most
representative for this tag (genre, usually). After that, pick a random song
from the first best nsongs of the selected artist and play it.

what-is-playing

Return an array with two strings. The first string is the currently playing
artist and the seconds one the currently playing song name. Both are NIL if
nothing is playing.

what-is-playing-as-string

Return a printable representation of the artist and song currently
playing. Returns NIL if the player is stopped.

song-lyrics

Get the song lyrics for the currently playing song

love-song

Use the lastfm library to add the currently playing song to the last.fm
loved list for the configured user. Authentication is needed for this
function to work. See the `lastfm` installation requirements.

unlove-song

Similar as `love-song`, only it removes the songs from the list.

next-song

Play the next songs in the playlist

stop

Stop the player

Interfaces exported from lyrics

search-song

Return a list of entries, where each entry is a list with the artist name,
the song name and the verse line where the lyrics appears. The artist name and
song can be used to request the full lyrics. There can be multiple entries for
the same artist/song combination.

Interfaces Exported from youtube

play/pause

Toggle playing status.

replay

Rewind the song at the beginning, effectively replaying it.

seek seconds

Forward or backward play by seconds, if the seconds is negative.

percent-pos

Current playing song position, in percent.

time-pos

Current playing song position, in seconds, as string.

duration

Current playing song duration, in MM:SS format, as string.

switch-to-browser &key (from-beginning nil)

Pause the player and open the youtube page of the current playing song in the
user default browser. If `from-beginning` is T, start playing from the beginning,
otherwise continue from where the player was. 

turn-video-on

Quit mpv and restart it in video mode, locally (i.e. not in the browser)

Authors

Copyright (c) 2019 Mihai Olteanu

Licensed under the GPLv3 license.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 zbucium

Author

Mihai Olteanu

License

GPLv3

Description

last.fm music player with lyrics

Version

0.1

Dependencies
Source

zbucium.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 zbucium.asd

Location

zbucium.asd

Systems

zbucium (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 zbucium/packages.lisp

Parent

zbucium (system)

Location

packages.lisp

Packages

zbucium


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 zbucium/zbucium.lisp

Dependency

packages.lisp (file)

Parent

zbucium (system)

Location

zbucium.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 zbucium

Source

packages.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: love-song ()
Package

zbucium

Source

zbucium.lisp (file)

Function: next-song ()

Close the current youtube session, forcing the generator to take and play the next song.

Package

zbucium

Source

zbucium.lisp (file)

Function: play-album ARTIST ALBUM
Package

zbucium

Source

zbucium.lisp (file)

Function: play-artist ARTIST NSONGS RANDOM
Package

zbucium

Source

zbucium.lisp (file)

Function: play-artist-similar ARTIST NARTISTS NSONGS
Package

zbucium

Source

zbucium.lisp (file)

Function: play-my-loved-songs NSONGS RANDOM
Package

zbucium

Source

zbucium.lisp (file)

Function: play-song ARTIST SONG

Play and replay a single song

Package

zbucium

Source

zbucium.lisp (file)

Function: play-tag TAG NSONGS RANDOM
Package

zbucium

Source

zbucium.lisp (file)

Function: play-tag-similar TAG NARTISTS NSONGS
Package

zbucium

Source

zbucium.lisp (file)

Function: play-user-songs USERNAME NSONGS RANDOM
Package

zbucium

Source

zbucium.lisp (file)

Function: song-lyrics ()
Package

zbucium

Source

zbucium.lisp (file)

Function: stop ()
Package

zbucium

Source

zbucium.lisp (file)

Function: unlove-song ()
Package

zbucium

Source

zbucium.lisp (file)

Function: what-is-playing ()
Package

zbucium

Source

zbucium.lisp (file)

Function: what-is-playing-as-string ()

Return a printable representation of the artist and song currently playing. If the player is stopped, return an empty string.

Package

zbucium

Source

zbucium.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: +scrobble-timeout+

Time to wait, in seconds, before scrobbling the current playing song.

Package

zbucium

Source

zbucium.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Special variables

Special Variable: *artist*

The name of the currently playing artist.

Package

zbucium

Source

zbucium.lisp (file)

Special Variable: *playing-thread*

Playing a song or list of songs starts a new thread since we also want to return from the call while the player is running.

Package

zbucium

Source

zbucium.lisp (file)

Special Variable: *song*

The name of the currently playing song.

Package

zbucium

Source

zbucium.lisp (file)

Special Variable: *still-playing*

Set to true when player started, set to nil when stopped.

Package

zbucium

Source

zbucium.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: play-simple SONGS-GENERATOR

The main functionality. Take a new song from the generator, save the lyrics for it, scrobble it if needed and either find a youtube url to play or create a string that can be searched by youtube-dl. Repeat after the song finishes or was stopped by the user. End the loop only when the player is stopped by the user.

Package

zbucium

Source

zbucium.lisp (file)

Function: set-playing-song ARTIST-AND-SONG
Package

zbucium

Source

zbucium.lisp (file)

Function: start-playing ()
Package

zbucium

Source

zbucium.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   Z  
Index Entry  Section

F
File, Lisp, zbucium.asd: The zbucium<dot>asd file
File, Lisp, zbucium/packages.lisp: The zbucium/packages<dot>lisp file
File, Lisp, zbucium/zbucium.lisp: The zbucium/zbucium<dot>lisp file

L
Lisp File, zbucium.asd: The zbucium<dot>asd file
Lisp File, zbucium/packages.lisp: The zbucium/packages<dot>lisp file
Lisp File, zbucium/zbucium.lisp: The zbucium/zbucium<dot>lisp file

Z
zbucium.asd: The zbucium<dot>asd file
zbucium/packages.lisp: The zbucium/packages<dot>lisp file
zbucium/zbucium.lisp: The zbucium/zbucium<dot>lisp file

Jump to:   F   L   Z  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   F   L   N   P   S   U   W  
Index Entry  Section

F
Function, love-song: Exported functions
Function, next-song: Exported functions
Function, play-album: Exported functions
Function, play-artist: Exported functions
Function, play-artist-similar: Exported functions
Function, play-my-loved-songs: Exported functions
Function, play-simple: Internal functions
Function, play-song: Exported functions
Function, play-tag: Exported functions
Function, play-tag-similar: Exported functions
Function, play-user-songs: Exported functions
Function, set-playing-song: Internal functions
Function, song-lyrics: Exported functions
Function, start-playing: Internal functions
Function, stop: Exported functions
Function, unlove-song: Exported functions
Function, what-is-playing: Exported functions
Function, what-is-playing-as-string: Exported functions

L
love-song: Exported functions

N
next-song: Exported functions

P
play-album: Exported functions
play-artist: Exported functions
play-artist-similar: Exported functions
play-my-loved-songs: Exported functions
play-simple: Internal functions
play-song: Exported functions
play-tag: Exported functions
play-tag-similar: Exported functions
play-user-songs: Exported functions

S
set-playing-song: Internal functions
song-lyrics: Exported functions
start-playing: Internal functions
stop: Exported functions

U
unlove-song: Exported functions

W
what-is-playing: Exported functions
what-is-playing-as-string: Exported functions

Jump to:   F   L   N   P   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   S  
Index Entry  Section

*
*artist*: Internal special variables
*playing-thread*: Internal special variables
*song*: Internal special variables
*still-playing*: Internal special variables

+
+scrobble-timeout+: Internal constants

C
Constant, +scrobble-timeout+: Internal constants

S
Special Variable, *artist*: Internal special variables
Special Variable, *playing-thread*: Internal special variables
Special Variable, *song*: Internal special variables
Special Variable, *still-playing*: Internal special variables

Jump to:   *   +  
C   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   Z  
Index Entry  Section

P
Package, zbucium: The zbucium package

S
System, zbucium: The zbucium system

Z
zbucium: The zbucium system
zbucium: The zbucium package

Jump to:   P   S   Z