Add-on:AmbiBox

2014-17-Sep
Another Major Update There have been a number of updates since June. Please note some of these will require a trip through the settings page to get things configured. Unfortunately, multithreading had to be dropped because of issues in the way that XBMC uses python, however the program is now multithreaded by default. Please read below for details on the new features, but as a list, these include:
 * 1) Better overall performance using CTypes for copying the memory buffer (under the hood).
 * 2) Configurable quality levels that can decrease performance impact, based on the number of LEDs you have.
 * 3) The ability to throttle the number of frames being sent.
 * 4) The ability to configure a delay in cases where the LEDs are changing prior to the video on the screen.
 * 5) Better handling of XBMC Direct - configure one profile and that will be used for all aspect ratios as well as 3D.
 * 6) Built-in hotkeys, not requiring modification of keyboard.xml for turning LEDs on/off, changing the LED delay and capturing a snapshot of the buffer.
 * 7) An optimization routine that attempts to find settings that work for your system (experimental at this time)

2014-10-Jun
Major Update This update requires the use of XBMC Gotham (13.0) or higher.

This repo forbids the inclusion of compiled files in the distribution. Due to this, we have removed mediainfo.dll from the package, however it may be downloaded and installed from the settings page as long as you have a network connection. This dll provides enhanced functionality in detecting video's display aspect ratio (DAR) for switching profiles based on this. In addition it provides information when using the 'XBMCDirect' capture mode.

This new release does away with the use of the xml file for configuring the profiles for different aspect ratios and there is now a page in the settings to do this. Previous users of the 'dardata.xml' will need to reconfigure, but the add-on now reads the current profile names from the AmbiBox program, easing the transition. There are a number of other new features. These are detailed below.

Features

 * Configurable default profile to use when Ambibox starts
 * Configurable audio profile to use during audio only content
 * A choice of settings to use when video playback starts
 * 1) Use a default video profile for all video content
 * 2) Display a menu of video profiles when playback starts that the user can choose from
 * 3) Automatically switch profiles based upon the aspect ratio of the video file playing (if discoverable, see below). This method requires editing of an XML file
 * 4) Turn off LEDs
 * Configure XBMC to capture frames if using the XBMC Direct method of capture
 * Configurable profiles to use for 3D video content (this is based strictly on the XBMC recommended filenames for video content see here)

Overview
There are three ways of installing the script currently:
 * 1) During installation of the Ambibox program the script is copied to the correct location.
 * 2) You can install it directly from the Official repo.
 * 3) You can download the zip file and manually copy it to the XBMC Add-Ons folder, overwriting the previous version.

The most recent version of the script can be downloaded here: https://github.com/AmbiBox/AmbiBox-XBMC/archive/master.zip

Details
It is assumed that you have already installed the AmbiBox application prior to installing this script. To manually install the script, first unzip the script to a convenient, temporary location and then copy the entire directory named ‘script.ambibox’ with its structure intact to the XBMC add-ons directory. In windows, this is typically located on your system drive at 'Users/Username/AppData/Roaming/XBMC/addons/'. If you have a previous installation, please back it up to a safe place before installing.

Overview
In XBMC go to System > Add-Ons > Enabled Add-Ons > Services > AmbiBox > Configure

Most of the features require that profiles are set up in the Ambibox program itself. It is suggested that you set up profiles (in Ambibox) for:
 * 1) Your entire screen using the capture method of your choosing. If using XBMCDirect, this will be used for all aspect ratios and 3D modes.
 * 2) For ColorMusic should you want an LED display based on sound only (Suggested choose Mode [Software] Plugins: Colormusic).
 * 3) For common video files that you play that have a different aspect ratio than your full screen (i.e. 4:3, 2.35:1), if not using XBMCDirect.
 * 4) If you use 3D, you will also need profiles that capture based on the underlying content (TAB vs SBS), again only if not using XBMCDirect.

Settings - General
On the first page you can specify which IP address and port that the AmbiBox windows application is using for communication. This will typically be at the local host at 127.0.0.1 and port 3636. As shown. You can also choose to turn on or off notifications, but it is recommended that you leave them on until you are confident that things are working as expected.

Next you can have the add-on check whether the AmbiBox program is running at the time XBMC starts and if it is installed, it will start it. If started this way, it will be closed when XBMC is closed. In rare circumstances, if XBMC exits with an error, AmbiBox won't be stopped. This will cause an error when relaunching XBMC because of a continued file lock on the XBMC log file. This can be remedied by closing AmbiBox manually.

If you are making changes to profiles in the AmbiBox program while running XBMC, these changes will not be reflected in the menu choices in the settings pages without refreshing them. Selecting 'Refresh profiles from AmbiBox will refresh them, but it requires hitting back twice to go to the AddOns/Services page and then coming back to the Settings page for AmbiBox.

The following dll is being deprecated. Although clunky, it seems that reading the video dimensions and frame rate are best done from the log and the script attempts to do that. However, in the case that fails (and it almost never does), there is a setting, if selected, that will download a third-party dll - mediainfo.dll to the script.ambibox/resources/lib folder. This dynamic link library provides added functionality to the add-on. It allows the examination of most video files at the time of playing them in XBMC in order to discover their dimensions and DAR. XBMC alone can provide the aspect ratio in most, but not all circumstances and does not provide the dimensions. Specifically, it does not provide this many times when using an external player. In addition, if using XBMCDirect and there is a need for using the highest resolution of capture (this is extremely unlikely), the add-on will use the information provided by mediainfo.dll to provide a full resolution video stream to AmbiBox for processing. More on this below. Mediainfo is Copyright (c) 2002-2014 MediaArea.net SARL. All rights reserved. The distribution and use is governed by a BSD-style license.

Settings - Profiles
The first option is to setup and enable a default profile. If this is not specified, XBMC will launch with whatever profile is currently being utilized by the AmbiBox windows application. This will be used for the LEDs while in the XBMC GUI. Note that if the profile is using XBMCDirect capture mode, the LEDs will remain dark since this mode only works while video content is playing. The next option is to enable and specify a profile for use during music playback. Typically this would be a profile utilizing either the built-in ColorMusic mode or the ColorMusic plugin in the AmbiBox application. The same precautions are needed when typing in the name of the profile to ensure that it exactly matches one of your named profiles.

There are four choices for profile switching during video playback:


 * 1)	Use a default video profile. This is as above where the profile name is specified and used during video playback, similar to the default and audio profiles.
 * 2)	Autoswitch based upon AR. This option attempts to read the aspect ratio of the video file and then chooses a profile based upon that aspect ratio.


 * Using this mode requires that the user has setup different profiles for different aspect ratios in the AmbiBox windows application. For instance for users with standard HD sets, there might be a profile for video that is fullscreen 16:9 such as most full screen HD television shows, another for 4:3 for most SD television shows and one at 2.35:1 or 2.40:1 for many movies. These are configured on the next two pages of settings.


 * 3)	Show Menu of profiles. Using this option, at the time of video playback, a menu of the currently available profiles that have been setup in the AmbiBox windows application is displayed and the used may select which profile to use. One thing to note is that for users utilizing external video player applications, such as MPC-HC, the player will cover the XBMC window and the menu of choices. This would require the user to minimize the player window temporarily in order to access the menu.


 * 4)	Turn off LED’s. The LED’s are off during video playback.

Next, there is an option to indicate that the AmbiBox windows application is using a screen capture mode with the XBMCDirect method. This method of capture can only be utilized when using the native video player and thus can be turned off if not using XBMCDirect or are using an external player. The following setting configures the amount of data sent to AmbiBox for processing. In most circumstances, this can be left on low. In testing on an LED setup with 140 LEDs, the accuracy of the lights was the same between low and the highest setting. Keeping the setting on low may decrease processing overhead and the may be desired on systems with limited processing power. At the highest setting, full frame video is sent for processing. The other settings are in between. In the case that the highest setting is chosen and the actual video dimensions can not be discovered, video at the dimensions of the display is sent.

Last, there is a setting to disable the LEDs when the screensaver is started. If the user has manually turned off the lights (Hotkey Cntrl-F7) the LEDs will NOT be re-enabled when waking from the screensaver.

Settings - 2D Aspect ratio profiles
These are the settings that are used when using the Auto switch based on AR mode. Here, the profiles that have been previously configured in AmbiBox to be used with full screen video of various aspect ratios are configured. The default is None. If no profile is configured for a given aspect ratio, the next closest one will be chosen.

Settings - 3D Aspect ratio profiles
Similar to the previous page, here the use of profiles configured with the use of 3D content can be configured. First, there is a toggle to attempt to use these modes. There is currently no standard way that video files are tagged as containing containing 3D content. XBMC and hence the plugin senses this through the way the file is named (see above).

Limitations

 * For modes other than PlayClaw or XBMCDirect, XBMC must be run in fullscreen windowed mode.
 * If using an external player and not using mediainfo, the DAR may not be detected by the system.
 * XBMCDirect does not work with external players.
 * XBMCDirect will only activate the lights while playing audio or video content. The lights will remain off in the XBMC GUI.
 * XBMCDirect will not work with most streaming video as opposed to playing from a file.
 * For LiveTV content that is in a DAR other than your display's DAR, there may be black bars embedded in the content. If the video is not zoomed to fill the display window, the capture areas may not be capturing areas with active video content. This is true for all capture modes.
 * XBMCDirect may not work with LiveTV SD content due to the black bar areas.
 * XBMCDirect does NOT work with DSPlayer builds of XBMC Gotham.
 * The automatic sensing of using a 3D mode in the GUI is not directly supported.
 * Currently only hSBS and hTAB 3D video modes are supported and in a limited fashion.

FAQs
Why would I want to go through the trouble of setting up all of these different profiles, my display is 16:9, why would I use other profiles?

When video files are played that have display aspect ratios that differ from your display, some people may either zoom or stretch the video so that it fills the screen. Under those circumstances, only one profile is needed because the video content reaches to the edge of the screen and can be correctly captured in order to drive the LED’s. The other, often preferred, method of display is using letterboxing or pillaring. Black or gray bars are placed either above and below or on either side of the video in order to display the content without distortion. In this case, there is no active video content in these areas and the AmbiBox application would be capturing whatever color is in those bars if it is using a standard setup to capture around the periphery of the display. By setting up different capture profiles for content with different aspect ratios, one can capture from the edge of the active content and have the LED’s display correctly.

Why don’t my LED’s light while music is playing?

I have set up a profile using ColorMusic and AmbiBox switches to it but the lights remain dark. AmbiBox cannot hook into the audio stream if you are using WASAPI for audio output. Please go to System -> System -> Audio Output and go to the very bottom (often times this setting isn’t seen if you do not scroll) to Audio Output Device and choose something other than WASAPI.

I am having an issues, how can I get help?

The two best places to get script help are: via the XBMC forum thread here: http://forum.kodi.tv/showthread.php?tid=198173 or via the Adafruit forums in this thread: http://forums.adafruit.com/viewtopic.php?f=47&t=36032

If you believe that things are not working as expected, please also include the version number of the script and any relevant entries in the XBMC logs in your post.