<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="pluginmanager2">

<info>
	<link type="guide" xref="index#extra"/>
	<link type="topic" xref="configuration#plugins"/>
        <desc>User plugin installation</desc>
</info>

	<title>Plugin Manager 2</title>

	<p>For updating or installing new plugins (extra channels or
	features), there's a user plugin manager. It's available as
	feature extension itself.</p>
	
	<steps>
	 <item><p>See the <key>F12</key> config dialog <key>🔌 Feature</key> section.</p></item>
	 <item><p>Enable the <key>⨯</key> Plugin Manager (listed near the end).</p></item>
	 <item><p>Restart streamtuner2 one last time for this change to take effect.</p></item>
	</steps>
	
	<p>Once activated it brings up a new <key>📦 Add</key> tab
	in the configuration window.</p>
	
	<p><media type="image" src="img/pluginmanager2.png"
	mime="image/png">Install dialog for user plugins</media></p>
	
	<p>You can scan for available/new plugins there. And have them
	downloaded right away. New plugins are just downloaded, not
	implictly enabled. Reopen the config dialog to see them in the
	regular <key>📻 Channels</key> or <key>🔌 Feature</key> tabs, and
	then enable them.</p>
	
	<note><p>Updated plugins will not be automatically loaded if they
	were enable already. That requires either a restart, or disabling +
	saving once, then reenabling them.</p></note>
	
	<section id="configuration">
	<title>Configuration</title>
	<list>
	<item><p>Alternative download repositories may be configured. (Little
	practical value at the moment.)</p></item>
	<item><p>And you can let the plugin manager handle autoactivation
	of changed plugin states.</p>
	  <list>
	  <item><p>After reconfiguring existing channel plugins, they get
   	  automatically instantiated or disabled in the user interface.
   	  (Which avoids the usual restart).</p></item>
	  <item><p>This currently doesn't work with feature/core
   	  plugins. Plugin deactivation is mostly visual, but does not undo
   	  menu extensions or undefine callback hooks.</p></item>
     	  </list>
     	</item>
   	</list>
	</section>

	<section id="configuration">
	<title>User plugins</title>
	<p>Downloaded plugins are stored in <file>~/.config/streamtuner2/plugins</file>.
	To remove them, delete the individual *.py files there manually.</p>
	<note style="bug"><p>Currently system-installed core plugins take
	precedence over downloaded updates.</p>
	<p>And you'll have to take care to eventually refresh/delete outdated user plugins,
	whenever you install a newer Streamtuner2 version.</p></note>
	</section>
	
	<section>
	<subtitle>Disable user plugin loading</subtitle>
	<p>Since this is still rather experimental, you may disable all
	associated features by starting ST2 via:</p>
	<screen>streamtuner2 -d <input>pluginmanager2</input></screen>
	<p>That'll inhibit loading this extension plugin. (Also works
	with any other plugin id.)</p>
	</section>

</page>
