diff options
| -rw-r--r-- | doc/developer-release.txt | 14 | ||||
| -rw-r--r-- | doc/emms.texinfo | 97 | ||||
| -rw-r--r-- | emms.info | 198 |
3 files changed, 210 insertions, 99 deletions
diff --git a/doc/developer-release.txt b/doc/developer-release.txt index a09081b..f197742 100644 --- a/doc/developer-release.txt +++ b/doc/developer-release.txt @@ -1,23 +1,19 @@ This is an explanation of how to make a release for Emms. Emms is -currently distributed in three different ways: via the Git repo on -Savannah, as a tarball from GNU, and via GNU ELPA. +developed at Savannah (https://savannah.gnu.org/projects/emms/) and +distributed via Emacs ELPA (https://elpa.gnu.org/). * Increase the version number in emms.el (variable, elpa header), Makefile * Update NEWS -* Push version updates to git repo +* Update the manual, then copy compiled emms.info to root directory + +* Push version updates to VCS * Tag release in VCS, for example `git tag -a 4.2 -m "4.2"' * Push tag to VCS if needed, for example `git push --tags origin "4.2"' -* Run make release - -* Run make upload - -* Update copy of emms.info in root directory - * Update online manual (cvs commit -m "update manual" manual/index.html) * Update website (cvs commit -m "update website" index.html) diff --git a/doc/emms.texinfo b/doc/emms.texinfo index 1480eba..43c5fc3 100644 --- a/doc/emms.texinfo +++ b/doc/emms.texinfo @@ -143,22 +143,22 @@ Emms, an online version of the manual is available at: The basic functionality of Emms consists of three parts: The core, the sources, and the players. -The core resides in @file{emms.el}, and provides a simple playlist and the -basic functionality to use all the other features of Emms. It provides -the common user commands and interfaces for other parts. It thinks in -tracks, where a track is the combination of a type and a name - e.g. -the track type 'file has a name that is the file name. Other track -types are possible. +The core resides in @file{emms.el}, provides a simple playlist, and +the basic functionality to use all the other features of Emms. It +provides the common user commands and interfaces for other parts. It +thinks in tracks, where a track is the combination of a type and a +name - e.g. the track type 'file has a name that is the file +name. Other track types are possible. To get to tracks, the core needs sources. The file @file{emms-source-file.el} provides simple sources to interact with the file system. When Emms finally has the sources in the playlist, it needs a player -to play them. @file{emms-player-simple.el} defines a few useful players, and -allows you to define your own in a very simple way. +to play them. @file{emms-player-simple.el} defines a few useful +players and provides a straightforward way of providing your own. -The Emms core comes with many additional features to extend its -functionality. +The Emms comes with many additional features to extend the +functionality beyond the core. The way Emms works is easy to customize with your own code or by using `M-x customize' or by changing the variables directly. @@ -172,7 +172,8 @@ This chapter demonstrates how to setup Emms so that you can start listening to your music without having to read all of the documentation first. This is the tl;dr version of the manual. -The first thing you have to do is telling Emacs where Emms is +The first thing you do is to load Emms via GNU ELPA. But if you are +installing manually, then start by telling Emacs where Emms is located. Let's say you have it in @file{~/elisp/emms/}. So add this line to your @file{.emacs}: @@ -185,7 +186,7 @@ installation chapter, @xref{Installation}. You'll then want to load Emms into Emacs. To achieve this you invoke the @code{emms-all} setup function by adding the following three lines -to your @file{.emacs}. +to your Emacs initialization file. @lisp (require 'emms-setup) @@ -208,16 +209,16 @@ the name of the file) of the music you listen to. Emms can use a number of pieces of software and libraries as sources for track info, see @xref{Track Information} for more. -The last thing to do is to tell Emms where your music is; the root +The last thing to do is to tell Emms where is your music; the root directory of our music collection. Let's say all your music is in -@file{~/Music} or in subdirectories thereof. +@file{~/Music} or in subdirectories thereof: @lisp (setq emms-source-file-default-directory "~/Music/") @end lisp -OK, now we've set up Emms. Reload your @file{.emacs} or restart Emacs to -let the changes have an effect. +OK, now we've set up Emms. Reload your Emacs initialization file or +restart Emacs to let the changes have an effect. Now we will add all our music to a playlist by invoking @kbd{M-x emms-add-directory-tree RET ~/Music/ RET}. We do this because then @@ -226,9 +227,9 @@ is also required for the Emms browser, @xref{The Browser}.) To switch to the playlist buffer, invoke @kbd{M-x emms-playlist-mode-go} or simply @kbd{M-x emms}. You may see that some -tracks are displayed with their file name, but as Emms populates its -tag cache, track by track, the filenames get replaced with the artist -and track name of the file's tag. +tracks are displayed with their file name, but as Emms asynchronously +populates its tag cache, track by track, the filenames get replaced +with the artist and track name of the file's tag. Go ahead and navigate to a track and hit @kbd{RET} on it to start playback. @@ -371,6 +372,7 @@ Another way to change Emms variables is to use the M-x @menu * Finding files and speed:: Finding files quickly or portably. +* Setup Examples:: Examples of ways to setup Emms. @end menu @@ -398,6 +400,63 @@ The method Emms will use is defined in the customisable variable @var{emms-source-file-directory-tree-function}. +@node Setup Examples +@section Setup Examples + +@cindex example +@cindex configuration + +What follow are samples from real-world Emms configurations which show +some of the variety and breadth of modifications people make to the +default Emms setup. + +The following excerpt includes dbus integration, defining a "recent" +filter for the @xref{The Browser}, persistent playlist via +@file{emms-history.el}, and enabling sending track information with +@file{emms-librefm-stream.el}: + +@lisp + ;; notifications + (require 'emms-dbus) + (emms-dbus-enable) + ;; covers + (setq emms-browser-covers #'emms-browser-cache-thumbnail-async) + (setq emms-browser-thumbnail-small-size 64) + (setq emms-browser-thumbnail-medium-size 128) + ;; filters + (emms-browser-make-filter "all" #'ignore) + (emms-browser-make-filter "recent" + (lambda (track) (< 30 + (time-to-number-of-days + (time-subtract (current-time) + (emms-info-track-file-mtime track)))))) + (emms-browser-set-filter (assoc "all" emms-browser-filters)) + ;; history + (emms-history-load) + ;; libre-fm + (emms-librefm-scrobbler-enable) +@end lisp + + +In the following it is possible to see how some of defaults are set +regarding saving playlists, playlist interaction, as well as adding +special arguments to a specific player backend. + +@lisp + (setq-default + emms-source-file-default-directory "/mnt/db/mediaCore/sound_music/" + + emms-source-playlist-default-format 'm3u + emms-playlist-mode-center-when-go t + emms-playlist-default-major-mode 'emms-playlist-mode + emms-show-format "NP: %s" + + emms-player-list '(emms-player-mpv) + emms-player-mpv-environment '("PULSE_PROP_media.role=music") + emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null")) +@end lisp + + @c ------------------------------------------------------------------- @node Getting Help @chapter Getting Help @@ -123,7 +123,7 @@ Emms, an online version of the manual is available at: The basic functionality of Emms consists of three parts: The core, the sources, and the players. - The core resides in 'emms.el', and provides a simple playlist and the + The core resides in 'emms.el', provides a simple playlist, and the basic functionality to use all the other features of Emms. It provides the common user commands and interfaces for other parts. It thinks in tracks, where a track is the combination of a type and a name - e.g. @@ -135,11 +135,11 @@ types are possible. system. When Emms finally has the sources in the playlist, it needs a player -to play them. 'emms-player-simple.el' defines a few useful players, and -allows you to define your own in a very simple way. +to play them. 'emms-player-simple.el' defines a few useful players and +provides a straightforward way of providing your own. - The Emms core comes with many additional features to extend its -functionality. + The Emms comes with many additional features to extend the +functionality beyond the core. The way Emms works is easy to customize with your own code or by using 'M-x customize' or by changing the variables directly. @@ -154,9 +154,10 @@ This chapter demonstrates how to setup Emms so that you can start listening to your music without having to read all of the documentation first. This is the tl;dr version of the manual. - The first thing you have to do is telling Emacs where Emms is -located. Let's say you have it in '~/elisp/emms/'. So add this line to -your '.emacs': + The first thing you do is to load Emms via GNU ELPA. But if you are +installing manually, then start by telling Emacs where Emms is located. +Let's say you have it in '~/elisp/emms/'. So add this line to your +'.emacs': (add-to-list 'load-path "~/elisp/emms/lisp/") @@ -165,7 +166,7 @@ installation chapter, *Note Installation::. You'll then want to load Emms into Emacs. To achieve this you invoke the 'emms-all' setup function by adding the following three lines to -your '.emacs'. +your Emacs initialization file. (require 'emms-setup) (emms-all) @@ -185,14 +186,14 @@ the name of the file) of the music you listen to. Emms can use a number of pieces of software and libraries as sources for track info, see *Note Track Information:: for more. - The last thing to do is to tell Emms where your music is; the root + The last thing to do is to tell Emms where is your music; the root directory of our music collection. Let's say all your music is in -'~/Music' or in subdirectories thereof. +'~/Music' or in subdirectories thereof: (setq emms-source-file-default-directory "~/Music/") - OK, now we've set up Emms. Reload your '.emacs' or restart Emacs to -let the changes have an effect. + OK, now we've set up Emms. Reload your Emacs initialization file or +restart Emacs to let the changes have an effect. Now we will add all our music to a playlist by invoking 'M-x emms-add-directory-tree RET ~/Music/ RET'. We do this because then Emms @@ -201,9 +202,9 @@ required for the Emms browser, *Note The Browser::.) To switch to the playlist buffer, invoke 'M-x emms-playlist-mode-go' or simply 'M-x emms'. You may see that some tracks are displayed with -their file name, but as Emms populates its tag cache, track by track, -the filenames get replaced with the artist and track name of the file's -tag. +their file name, but as Emms asynchronously populates its tag cache, +track by track, the filenames get replaced with the artist and track +name of the file's tag. Go ahead and navigate to a track and hit 'RET' on it to start playback. @@ -329,9 +330,10 @@ mechanism provided by Emacs. * Menu: * Finding files and speed:: Finding files quickly or portably. +* Setup Examples:: Examples of ways to setup Emms. -File: emms.info, Node: Finding files and speed, Up: Configuration +File: emms.info, Node: Finding files and speed, Next: Setup Examples, Up: Configuration 5.1 Finding files and speed =========================== @@ -353,6 +355,57 @@ installed. EMMS-SOURCE-FILE-DIRECTORY-TREE-FUNCTION. +File: emms.info, Node: Setup Examples, Prev: Finding files and speed, Up: Configuration + +5.2 Setup Examples +================== + +What follow are samples from real-world Emms configurations which show +some of the variety and breadth of modifications people make to the +default Emms setup. + + The following excerpt includes dbus integration, defining a "recent" +filter for the *Note The Browser::, persistent playlist via +'emms-history.el', and enabling sending track information with +'emms-librefm-stream.el': + + ;; notifications + (require 'emms-dbus) + (emms-dbus-enable) + ;; covers + (setq emms-browser-covers #'emms-browser-cache-thumbnail-async) + (setq emms-browser-thumbnail-small-size 64) + (setq emms-browser-thumbnail-medium-size 128) + ;; filters + (emms-browser-make-filter "all" #'ignore) + (emms-browser-make-filter "recent" + (lambda (track) (< 30 + (time-to-number-of-days + (time-subtract (current-time) + (emms-info-track-file-mtime track)))))) + (emms-browser-set-filter (assoc "all" emms-browser-filters)) + ;; history + (emms-history-load) + ;; libre-fm + (emms-librefm-scrobbler-enable) + + In the following it is possible to see how some of defaults are set +regarding saving playlists, playlist interaction, as well as adding +special arguments to a specific player backend. + + (setq-default + emms-source-file-default-directory "/mnt/db/mediaCore/sound_music/" + + emms-source-playlist-default-format 'm3u + emms-playlist-mode-center-when-go t + emms-playlist-default-major-mode 'emms-playlist-mode + emms-show-format "NP: %s" + + emms-player-list '(emms-player-mpv) + emms-player-mpv-environment '("PULSE_PROP_media.role=music") + emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null")) + + File: emms.info, Node: Getting Help, Next: Formats and Freedom, Prev: Configuration, Up: Top 6 Getting Help @@ -3370,12 +3423,14 @@ Concept Index * compiling: Compiling Emms. (line 6) * complex player: More Complex Player. (line 6) * Configuration: Configuration. (line 6) +* configuration: Setup Examples. (line 6) * core file: The Core File. (line 6) * core functions: Core Functions. (line 6) * defining info methods: Defining Info Methods. (line 6) * defining new players: New Player. (line 6) * defining players: Extending Emms. (line 6) * display emms information: Emms Mode Line. (line 6) +* example: Setup Examples. (line 6) * FDL, GNU Free Documentation License: The GNU FDL. (line 6) * files: Finding files and speed. (line 6) @@ -3757,59 +3812,60 @@ Keybinding Index Tag Table: Node: Top695 Node: Introduction4442 -Node: Quickstart Guide5901 -Node: Installation8652 -Node: Compiling Emms9201 -Node: Setup9889 -Node: Configuration10875 -Node: Finding files and speed12286 -Node: Getting Help13132 -Node: Formats and Freedom13710 -Node: Basic Commands14915 -Node: The Core File18296 -Node: User Variables18730 -Node: Hooks19706 -Node: Core Functions21132 -Node: Sources24132 -Node: Simple Players26265 -Node: Playlists27322 -Node: Track Information28603 -Node: Using tinytag31490 -Node: Using exiftool31919 -Node: Using TagLib32291 -Node: Defining Info Methods33400 -Node: Interactive Playlists34182 -Node: Markable Playlists37224 -Node: Extending Emms39695 -Node: New Player40131 -Node: Simple Player for `play'40520 -Node: More Complex Player42248 -Node: The Browser45255 -Node: Browser Interface46231 -Node: Filtering Tracks48645 -Node: Displaying Covers50423 -Node: Changing Looks52437 -Node: Sorting Playlists55415 -Node: Persistent Playlists56884 -Node: Editing Tracks58043 -Node: Emms Mode Line61717 -Node: Limiting62885 -Node: Music Player Daemon65224 -Node: Lyrics68737 -Node: Volume70785 -Node: Streaming Audio72573 -Ref: Streaming Audio-Footnote-173165 -Node: APE / FLAC Commands73516 -Node: Bookmarks74223 -Node: Managing Playlists74934 -Node: GNU FM75957 -Node: Uploading Track Information77311 -Node: GNU FM Streaming78193 -Node: Copying78693 -Node: The GNU FDL116210 -Node: Concept Index138598 -Node: Function Index143529 -Node: Variable Index159221 -Node: Keybinding Index161564 +Node: Quickstart Guide5910 +Node: Installation8778 +Node: Compiling Emms9327 +Node: Setup10015 +Node: Configuration11001 +Node: Finding files and speed12476 +Node: Setup Examples13345 +Node: Getting Help15278 +Node: Formats and Freedom15856 +Node: Basic Commands17061 +Node: The Core File20442 +Node: User Variables20876 +Node: Hooks21852 +Node: Core Functions23278 +Node: Sources26278 +Node: Simple Players28411 +Node: Playlists29468 +Node: Track Information30749 +Node: Using tinytag33636 +Node: Using exiftool34065 +Node: Using TagLib34437 +Node: Defining Info Methods35546 +Node: Interactive Playlists36328 +Node: Markable Playlists39370 +Node: Extending Emms41841 +Node: New Player42277 +Node: Simple Player for `play'42666 +Node: More Complex Player44394 +Node: The Browser47401 +Node: Browser Interface48377 +Node: Filtering Tracks50791 +Node: Displaying Covers52569 +Node: Changing Looks54583 +Node: Sorting Playlists57561 +Node: Persistent Playlists59030 +Node: Editing Tracks60189 +Node: Emms Mode Line63863 +Node: Limiting65031 +Node: Music Player Daemon67370 +Node: Lyrics70883 +Node: Volume72931 +Node: Streaming Audio74719 +Ref: Streaming Audio-Footnote-175311 +Node: APE / FLAC Commands75662 +Node: Bookmarks76369 +Node: Managing Playlists77080 +Node: GNU FM78103 +Node: Uploading Track Information79457 +Node: GNU FM Streaming80339 +Node: Copying80839 +Node: The GNU FDL118356 +Node: Concept Index140744 +Node: Function Index145821 +Node: Variable Index161513 +Node: Keybinding Index163856 End Tag Table |