From: Tim Vaughan Date: Thu, 12 Dec 2019 11:37:24 +0000 (+0100) Subject: Added remaining docstrings. Flycheck now happy. X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=commitdiff_plain;h=55bcbadba437769330aec82fe1ea4fcb1aacfe28;p=emus.git Added remaining docstrings. Flycheck now happy. --- diff --git a/emus.el b/emus.el index 7e2e64e..12c57f1 100644 --- a/emus.el +++ b/emus.el @@ -76,13 +76,33 @@ '((t :inherit bold)) "Face used for current track cursor") -;;; mpg123 process -;; + +;;; Global variables (defvar emus--proc-in-use nil "If non-nil, disables `emus-send-cmd'. Used to prevent commands from interfering with library construction.") +(defvar emus-tracks nil + "Emus audio library.") + +(defvar emus-current-track nil + "Currently-selected emus track.") + +(defvar emus-state 'stopped + "Current playback state.") + +(defvar emus-continuous-playback t + "If non-nil, emus will automatically play the next track when the current track is finished.") + +(defvar emus-current-volume 100 + "The current playback volume.") + + +;;; mpg123 process +;; + + (defun emus-get-process () "Return current or new mpg123 process." (let* ((emus-process-raw (get-process "emus-process")) @@ -123,9 +143,6 @@ be used by `emus--load-library'." "Get all mp3 files in main emus directory." (directory-files-recursively emus-directory ".*\\.mp3")) -(defvar emus-tracks nil - "Emus audio library.") - (defun emus-make-track (artist album title filename &optional pos) "Create an object representing an emus track. ARTIST, ALBUM and TITLE are used to describe the track, FILENAME @@ -229,10 +246,6 @@ by the filesystem." ;;; Playback ;; -(defvar emus-current-track nil) -(defvar emus-state 'stopped) -(defvar emus-continuous-playback t) - (defun emus--suspend-cp () "Suspend continuous playback." (setq emus-continuous-playback nil)) @@ -293,9 +306,6 @@ If the track is currently paused, resume playback." (unless (eq emus-state 'paused))) (emus--update-track emus-current-track)))) -(defvar emus-current-volume 100 - "The current playback volume.") - (defun emus-set-volume (pct) "Set the playback volume to PCT %." (emus--with-library @@ -411,6 +421,13 @@ If PREV is non-nil, plays the last track of the previous album." ;; (defun emus--insert-track (track &optional prev-track first) + "Insert a button representing TRACK into the current buffer. + +When provided, PREV-TRACK is used to determine whether to insert additional +headers representing the artist or the album title. + +If non-nil, FIRST indicates that the track is the first in the library +and thus requires both artist and album headers." (let* ((artist (emus-track-artist track)) (album (emus-track-album track)) (title (emus-track-title track)) @@ -458,6 +475,8 @@ If PREV is non-nil, plays the last track of the previous album." 'emus-track)))))) (defun emus--update-track (track) + "Rerender entry for TRACK in emus browser buffer. +Used to update browser display when `emus-current-track' and/or `emus-state' changes." (let ((track-pos (emus-track-browser-pos track))) (when (and (get-buffer "*emus*") (emus-track-browser-pos track)) @@ -472,6 +491,7 @@ If PREV is non-nil, plays the last track of the previous album." (goto-char old-point)))))) (defun emus--render-tracks () + "Render all library tracks in emus browser buffer." (with-current-buffer "*emus*" (let ((inhibit-read-only t) (old-pos (point))) @@ -484,15 +504,17 @@ If PREV is non-nil, plays the last track of the previous album." (goto-char old-pos)))) (defun emus--click-track (button) + "Begin playback of track indicated by BUTTON." (emus-play-track (button-get button 'emus-track)) (emus-display-status)) (defun emus-centre-current () + "Centre the current track in the browser buffer, if available." (interactive) (when (get-buffer "*emus*") - (when emus-current-track - (goto-char (emus-track-browser-pos emus-current-track)) - (recenter)))) + (when emus-current-track + (goto-char (emus-track-browser-pos emus-current-track)) + (recenter)))) (defun emus-browse () "Switch to *emus* audio library browser." @@ -504,24 +526,84 @@ If PREV is non-nil, plays the last track of the previous album." (emus-centre-current))) (defun emus-refresh () + "Refresh the emus library." (interactive) (emus-stop) (setq emus-tracks nil) (emus-browse)) -(defun emus-playpause-status () (interactive) (emus-playpause) (emus-display-status)) -(defun emus-stop-status () (interactive) (emus-stop) (emus-display-status)) -(defun emus-volume-up-status () (interactive) (emus-volume-up) (emus-display-status)) -(defun emus-volume-down-status () (interactive) (emus-volume-down) (emus-display-status)) -(defun emus-play-next-status () (interactive) (emus-play-next) (emus-display-status)) -(defun emus-play-prev-status () (interactive) (emus-play-prev) (emus-display-status)) -(defun emus-play-next-album-status () (interactive) (emus-play-next-album) (emus-display-status)) -(defun emus-play-prev-album-status () (interactive) (emus-play-prev-album) (emus-display-status)) -(defun emus-jump-10s-forward-status () (interactive) (emus-jump-10s-forward) (emus-display-status)) -(defun emus-jump-10s-backward-status () (interactive) (emus-jump-10s-backward) (emus-display-status)) -(defun emus-centre-current-status () (interactive) (emus-centre-current) (emus-display-status)) + +;;; Playback + status display commands +;; + +(defun emus-playpause-status () + "Start, pause or resume playback, then display the emus status in the minibuffer." + (interactive) + (emus-playpause) + (emus-display-status)) + +(defun emus-stop-status () + "Stop playback, then display the emus status in the minibuffer." + (interactive) + (emus-stop) + (emus-display-status)) + +(defun emus-volume-up-status () + "Increase volume by 10%, then display the emus status in the minibuffer." + (interactive) + (emus-volume-up) + (emus-display-status)) + +(defun emus-volume-down-status () + "Decrease volume by 10%, then display the emus status in the minibuffer." + (interactive) + (emus-volume-down) + (emus-display-status)) + +(defun emus-play-next-status () + "Play next track, then display the emus status in the minibuffer." + (interactive) + (emus-play-next) + (emus-display-status)) + +(defun emus-play-prev-status () + "Play previous track, then display the emus status in the minibuffer." + (interactive) + (emus-play-prev) + (emus-display-status)) + +(defun emus-play-next-album-status () + "Play first track of next album, then display the emus status in the minibuffer." + (interactive) + (emus-play-next-album) + (emus-display-status)) + +(defun emus-play-prev-album-status () + "Play last track of previous album, then display the emus status in the minibuffer." + (interactive) + (emus-play-prev-album) + (emus-display-status)) + +(defun emus-jump-10s-forward-status () + "Jump 10s forward in current track, then display the emus status in the minibuffer." + (interactive) + (emus-jump-10s-forward) + (emus-display-status)) + +(defun emus-jump-10s-backward-status () + "Jump 10s backward in current track, then display the emus status in the minibuffer." + (interactive) + (emus-jump-10s-backward) + (emus-display-status)) + +(defun emus-centre-current-status () + "Jump 10s backward in current track, then display the emus status in the minibuffer." + (interactive) + (emus-centre-current) + (emus-display-status)) (defun emus-refresh-status () + "Refresh the emus library, then display the emus status in the minibuffer." (interactive) (emus-stop) (setq emus-tracks nil) @@ -560,7 +642,7 @@ If PREV is non-nil, plays the last track of the previous album." (kbd ".") 'emus-jump-10s-forward-status (kbd "c") 'emus-centre-current-status)) map) - "Keymap for emus.") + "Keymap for emus browser.") (define-derived-mode emus-browser-mode special-mode "emus-browser" "Major mode for EMUS music player file browser.")