Implemented --args-feature

* as discussed in #1532, with args-parameter, and optionally
   inserted config-key
 * updated changelog/docs

beetsplug/play.py

@@ -35,7 +35,7 @@ class PlayPlugin(BeetsPlugin):
             'command': None,
             'use_folders': False,
             'relative_to': None,
-            'optargs': None,
+            'args': None,
         })
 
     def commands(self):
@@ -45,7 +45,7 @@ class PlayPlugin(BeetsPlugin):
         )
         play_command.parser.add_album_option()
         play_command.parser.add_option(
-            '-o', '--optargs',
+            '-A', '--args',
             action='store',
             help='Insert additional arguments into command string'
         )
@@ -59,13 +59,13 @@ class PlayPlugin(BeetsPlugin):
         command_str = config['play']['command'].get()
         use_folders = config['play']['use_folders'].get(bool)
         relative_to = config['play']['relative_to'].get()
-        confargs = config['play']['optargs'].get()
+        confargs = config['play']['args'].get()
         if relative_to:
             relative_to = util.normpath(relative_to)
 
         # Prepare command strings with optional args
-        if opts.optargs:
+        if opts.args:
-            command_str = command_str.format(opts.optargs or '')\
+            command_str = command_str.format(opts.args or '')\
                           .format(confargs or '')
             
         # Perform search by album and add folders rather than tracks to

docs/changelog.rst

@@ -26,7 +26,8 @@ New features:
   :bug:`1104` :bug:`1493`
 * :doc:`/plugins/plexupdate`: A new ``token`` configuration option lets you
   specify a key for Plex Home setups. Thanks to :user:`edcarroll`. :bug:`1494`
-
+* :doc:`/plugins/play`: A new option `--args`/`-A` has been added, used to
+  hand over options to the player.
 
 Fixes:
 

docs/plugins/play.rst

@@ -29,6 +29,12 @@ would on the command-line)::
 While playing you'll be able to interact with the player if it is a
 command-line oriented, and you'll get its output in real time.
 
+The ``--args``-argument can be used to pass additional parameters to the
+command. The position for these is marked by ``{}`` in the command-section.
+
+For additional features and usage of the ``--args``-argument, see the example
+below.
+
 Configuration
 -------------
 
@@ -37,10 +43,43 @@ configuration file. The available options are:
 
 - **command**: The command used to open the playlist.
   Default: ``open`` on OS X, ``xdg-open`` on other Unixes and ``start`` on
-  Windows.
+  Windows. Insert ``{}`` to make use of the ``--args``-feature.
 - **relative_to**: Emit paths relative to base directory.
   Default: None.
 - **use_folders**: When using the ``-a`` option, the m3u will contain the
   paths to each track on the matched albums. Enable this option to
   store paths to folders instead.
   Default: ``no``.
+- **optargs**: Static, additional parameters that may be inserted
+  using ``--args``. For this to work, you need ``{}`` inserted into your
+  command-section of the config file as well as into the parameter given to
+  ``--args`` (see example)
+
+Args-Example
+------------
+
+Assume you have the following in your config file::
+
+    play:
+	    command: player --opt1 arg1 {} --opt2
+		args: --opt3
+
+If you just call ``beet play`` without the usage of ``--args``, the command
+will be called as if the ``{}`` wasn't there::
+
+    player --opt1 arg1 --opt2
+
+If ``--args`` is given, the ``{}`` gets replaced by the argument, thus
+``beet play --args "--opt4"`` results in a call of::
+
+    player --opt1 arg1 --opt4 --opt2
+
+To insert the options configured with the args-key in the config-file,
+call ``beet play --args "{}"``, resulting in::
+
+    player --opt1 arg1 --opt3 --opt2
+
+Of course, this can be combined with other parameters as well, like in
+``beet play --args "{} --opt4"``, which calls the following::
+
+    player --opt1 arg1 --opt3 --opt4 --opt2