View source for FPP:Plugins

==FPP UI==
===Adding FPP Menu Entries===
We allow menu entries into each of the top-level menus.  These are drawn in the UI menus if your plugin incorporates a specially named file for each menu entry.  To include something in the "Status/Control" menu, you must include a file named "status_menu.inc".  The contents of this file should be a list element and link with text.  The menu styling will happen automatically as it will be included within the proper menu's unordered list.

{| class="wikitable"
|-
! Status/Control !! Content Setup !! Output Setup !! Help
|-
| status_menu.inc || content_menu.inc || output_menu.inc || help_menu.inc
|-
|}

'''Example'''

Prerequisites:
* You're writing a plugin called "RDS Plugin"
* Your plugin's repository name is "rds_plugin" (passed to plugin.php's "plugin" parameter)
* You want a menu entry titled "RDS Setup" under "Output Setup" that will link to your plugin's "rds_setup.php" page for configuration

Your output_menu.inc:
<pre>
<li><a href="plugin.php?plugin=rds_plugin&page=rds_setup.php">RDS Setup</a></li>
</pre>

Of course, you must have a file named "rds_setup.php" in your plugin as well, so that when you click the menu entry, your page is drawn.

===Adding FPP Plugin Pages===
You can write pages that will be drawn using plugin.php.  The main page takes care of the main UI details such as the menu entries, session support, header, footer, etc.  Your page will only need to include the content within the "bodyWrapper" div of the main FPP UI layout.

To access your page you must use plugin.php and include at least two GET variables.

* '''plugin''' - This is the directory name of your plugin.  It will be the same as the name of your git repository.
* '''page''' - The name of the page within your plugin directory to be included.

'''Example'''

Here's a quick example of a demo_page.php:
<pre>
<h1><?php echo "Hello World"; ?></h1>
<p>
This is a demo plugin page.
</p>
</pre>

==FPP Daemon==
The daemon supports callbacks during execution.  These are useful to get data from the daemon without having to query the FPPD socket or running your own daemon to parse certain details.
==Plugin Types==
Currently there are only 3 types, but we may support more in the future for things like starting/stopping FPPD, and others.  When FPPD starts, it will run a binary called "callbacks" with the "--list" parameter.  This should return a comma-delimited list of callback types that your plugin supports.  FPPD will keep track of this and call your function when one of the supported types occurs.
===Media===
This is a callback for when a media playback is started.  If there is an audio file associated with the media being played back, TagLib is used to attempt parsing of the embedded metadata tags to be passed to the plugin.  The plugin's "callbacks" executable will be called with "--type media" option as well as the relevant data.  It is JSON formatted data.

{| class="wikitable"
|-
! key !! value !! description
|-
| type || {both|media|sequence|pause|video|event} || Type of media entry being played back 
|-
| Sequence || <filename> || Name of the .fseq being played 
|-
| Media || <filename> || Media filename (if present) 
|-
| title || <parsed tag> || Media Metadata Title (if present) 
|-
| artist || <parsed tag> || Media Metadata Artist (if present)
|-
| album  || <parsed tag> || Media Metadata Album (if present)
|-
| year   || <parsed tag> || Media Metadata Year (if present)
|-
| comment || <parsed tag> || Media Metadata comment (if present)
|-
| track || <parsed tag> || Media Metadata Track Number (if present)
|-
| genre || <parsed tag> || Media Metadata Genre (if present)
|-
| seconds || <parsed tag> || Media Metadata Seconds (if present)
|-
| minutes || <parsed tag> || Media Metadata Minutes (if present)
|-
| bitrate || <parsed tag> || Media Metadata Bitrate (if present)
|-
| sampleRate || <parsed tag> || Media Metadata Sample Rate (if present)
|-
| channels || <parsed tag> || Media Metadata Channels (if present)
|-
|}

====Example Use Case====
A script to update your website with the currently playing song, update a matrix with the song, etc.

====Example of a media callback execution====
<pre>
/opt/fpp/plugins/rds_plugin/callbacks --type media --data {"type":"both","Sequence":"rds test.fseq","Media":"test song.mp3","title":"Song Title","artist":"Song Artist"}
</pre>

'''NOTE''': This callback is non-blocking.  In other words, if your callback is written poorly and doesn't return for 20 seconds, FPPD should not be negatively affected and should start playback of the sequence without waiting.

===Playlist===
This is a callback for when a playlist is started.  When a schedule determines that a playlist should be playing, it loads the details and makes this callback.  Currently it only passes the sequence names to the plugin, but may be expanded in the future.  The plugin's "callbacks" executable will be called with "--type playlist" option as well as the relevant data.  It is JSON formatted data that includes the sequence details as well as whether it is starting or stopping as values "start"/"stop" to key "Action."

====Example Use Case====
A script to turn on/off GPIO pins that control relays for power to your show, or send a tweet alerting people that your show is starting/stopping.

====Example of a playlist callback execution====
<pre>
/opt/fpp/plugins/rds_plugin/callbacks --type media --data {"Sequence":"rds test.fseq","Sequence":"rds test 2.fseq","Action":"start"}
</pre>

'''NOTE''': This callback is blocking.  In other words, if your callback is written poorly and doesn't return for 20 seconds, FPPD will show the delay.

===Next Playlist Entry===
Currently unimplemented, but will be implemented soon.  Unsure on implementation details at this point, but the purpose for this plugin will be to allow a plugin to control the order of items played by FPPD.  Think of a jukebox plugin, or something where a controller outside of FPPD will determine the next playlist entry.

====Example Use Case====
A user-facing queue system so your viewers can select the next song from a list, or a jukebox random plugin.

'''NOTE''': This callback is blocking.  In other words, if your callback is written poorly and doesn't return for 20 seconds, FPPD will show the delay.

==Plugin Requirements and Installation==