nirv.git

.\" nirv - music player
.\" Copyright (C) 2023 ArcNyxx
.\" see LICENCE file for licensing information
.TH NIRV 1 nirv\-VERSION
.SH NAME
nirv \- music player
.SH SYNOPSIS
.SY nirv
.YS
.SH DESCRIPTION
.BR nirv (1)
is a music player which reads from
.B flac
files and plays via the default
.B alsa
device.
.PP
.BR nirv (1)
accepts real-time signals to toggle pause and skip time, and accesses a
symbolic link to find the next song.
.BR nirv (1)
frequently writes song metadata to a regular file.  This file should always be
read atomically by filling a buffer with a single
.BR read (2).
.BR nirv (1)
creates an empty file when it plays the next song.
.PP
It is recommended that a shell script is used to quickly combine these
functions of
.BR nirv (1)
to extend its functionality and usefulness as a full music player.
.SH SIGNALS
.TP
.BR SIGINT \ or\  SIGTERM
Terminate
.BR nirv (1)
cleanly.
.TP
.B SIGRTMIN+1
Toggle pause.  When
.BR nirv (1)
accesses a new song, it will play immediately.
.TP
.BR SIGRTMIN+2 \ [ \fInum\fB ]
Skip a number of seconds forward, with a positive value, or backward, with a
negative value.  If there is not enough time elapsed or remaining in the song,
.BR nirv (1)
will restart or end the song respectively.
.SH FILES
.TP
.B /tmp/nirv-song
A symbolic link to the next song to be played.  This is automatically accessed
by
.BR nirv (1)
when the previous song ends.  If it does not exist,
.BR nirv (1)
pauses until it does.
.TP
.B /tmp/nirv-info
A regular file which contains a list of newline-terminated strings with the
following values: the
.BR realpath (3)
value of the currently playing song; the vorbis comments TITLE, AUTHOR, and
ALBUM; and two numbers: the time elapsed, and the total time in the song, both
in the format
.IR minutes : seconds .
.SH AUTHOR
Written by ArcNyxx.
.SH SEE ALSO
.BR nctl (1),\  flac (1),\  amixer (1),\  ln (1),\  read (2),\  realpath (3),
.BR signal (7),\  symlink (7)