Visualization

Detailed Description

Class: kodi::addon::CInstanceVisualization

Visualization add-on instance
Music visualization, or music visualisation, is a feature in Kodi that generates animated imagery based on a piece of music. The imagery is usually generated and rendered in real time synchronized to the music.

Visualization techniques range from simple ones (e.g., a simulation of an oscilloscope display) to elaborate ones, which often include a plurality of composited effects. The changes in the music's loudness and frequency spectrum are among the properties used as input to the visualization.

Include the header #include <kodi/addon-instance/Visualization.h> to use this class.

This interface allows the creation of visualizations for Kodi, based upon DirectX or/and OpenGL rendering with C++ code.

Additionally, there are several other functions available in which the child class can ask about the current hardware, including the device, display and several other parts.

---

Here's an example on addon.xml:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="visualization.myspecialnamefor"
  version="1.0.0"
  name="My special visualization addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="xbmc.player.musicviz"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My visualization addon addon</summary>
    <description lang="en_GB">My visualization addon description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Description to visualization related addon.xml values:

Name	Description
point	Addon type specification At all addon types and for this kind always "xbmc.player.musicviz".
library_@PLATFORM@	Sets the used library name, which is automatically set by cmake at addon build.

---

Here is an example of the minimum required code to start a visualization:

#include <kodi/addon-instance/Visualization.h>
 
class CMyVisualization : public kodi::addon::CAddonBase,
                         public kodi::addon::CInstanceVisualization
{
public:
  CMyVisualization();
 
  bool Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName) override;
  void AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength) override;
  void Render() override;
};
 
CMyVisualization::CMyVisualization()
{
  ...
}
 
bool CMyVisualization::Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName)
{
  ...
  return true;
}
 
void CMyVisualization::AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength)
{
  ...
}
 
void CMyVisualization::Render()
{
  ...
}
 
ADDONCREATOR(CMyVisualization)

---

Here is another example where the visualization is used together with other instance types:

#include <kodi/addon-instance/Visualization.h>
 
class CMyVisualization : public kodi::addon::CInstanceVisualization
{
public:
  CMyVisualization(KODI_HANDLE instance, const std::string& version);
 
  bool Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName) override;
  void AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength) override;
  void Render() override;
};
 
CMyVisualization::CMyVisualization(KODI_HANDLE instance, const std::string& version)
  : kodi::addon::CInstanceAudioDecoder(instance, version)
{
  ...
}
 
bool CMyVisualization::Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName)
{
  ...
  return true;
}
 
void CMyVisualization::AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength)
{
  ...
}
 
void CMyVisualization::Render()
{
  ...
}
 
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() { }
  ADDON_STATUS CreateInstance(int instanceType,
                              const std::string& instanceID,
                              KODI_HANDLE instance,
                              const std::string& version,
                              KODI_HANDLE& addonInstance) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_VISUALIZATION)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my visualization");
    addonInstance = new CMyVisualization(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyVisualization is called from Kodi's header. Manually deleting the add-on instance is not required.

Modules
	Definitions, structures and enumerators
	Visualization add-on instance definition values All visualization functions associated data structures.
	Information functions
	To get info about the device, display and several other parts These are functions to query any values or to transfer them to Kodi.

Function Documentation

CInstanceVisualization() [1/2]

CInstanceVisualization ( )

inline

Visualization class constructor.

Used by an add-on that only supports visualizations.

CInstanceVisualization() [2/2]

CInstanceVisualization ( KODI_HANDLE  instance, const std::string &  kodiVersion = ""  )

inlineexplicit

Visualization class constructor used to support multiple instance types.

Parameters

[in]	instance	The instance value given to kodi::addon::CAddonBase::CreateInstance(...).
[in]	kodiVersion	[opt] Version used in Kodi for this instance, to allow compatibility to older Kodi versions.

Note

Recommended to set kodiVersion.

---

Here's example about the use of this:

class CMyVisualization : public kodi::addon::CInstanceAudioDecoder
{
public:
  CMyVisualization(KODI_HANDLE instance, const std::string& kodiVersion)
    : kodi::addon::CInstanceAudioDecoder(instance, kodiVersion)
  {
     ...
  }
 
  ...
};
 
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  kodi::Log(ADDON_LOG_INFO, "Creating my visualization");
  addonInstance = new CMyVisualization(instance, version);
  return ADDON_STATUS_OK;
}

~CInstanceVisualization()

~CInstanceVisualization ( )

overridedefault

Destructor.

Start()

virtual bool Start ( int  channels, int  samplesPerSec, int  bitsPerSample, std::string  songName  )

inlinevirtual

Used to notify the visualization that a new song has been started.

Parameters

[in]	channels	Number of channels in the stream
[in]	samplesPerSec	Samples per second of stream
[in]	bitsPerSample	Number of bits in one sample
[in]	songName	The name of the currently-playing song

Returns

true if start successful done

Stop()

virtual void Stop ( )

inlinevirtual

Used to inform the visualization that the rendering control was stopped.

AudioData()

virtual void AudioData ( const float *  audioData, int  audioDataLength, float *  freqData, int  freqDataLength  )

inlinevirtual

Pass audio data to the visualization.

Parameters

[in]	audioData	The raw audio data
[in]	audioDataLength	Length of the audioData array
[in]	freqData	The FFT of the audio data
[in]	freqDataLength	Length of frequency data array

Values freqData and freqDataLength are used if GetInfo() returns true for the wantsFreq parameter. Otherwise, freqData is set to nullptr and freqDataLength is 0.

IsDirty()

virtual bool IsDirty ( )

inlinevirtual

Used to inform Kodi that the rendered region is dirty and need an update.

Returns

True if dirty

Render()

virtual void Render ( )

inlinevirtual

Used to indicate when the add-on should render.

GetInfo()

virtual void GetInfo ( bool &  wantsFreq, int &  syncDelay  )

inlinevirtual

Used to get the number of buffers from the current visualization.

Parameters

[out]	wantsFreq	Indicates whether the add-on wants FFT data. If set to true, the freqData and freqDataLength parameters of AudioData() are used
[out]	syncDelay	The number of buffers to delay before calling AudioData()

Note

If this function is not implemented, it will default to wantsFreq = false and syncDelay = 0.

GetPresets()

virtual bool GetPresets ( std::vector< std::string > &  presets )

inlinevirtual

Used to get a list of visualization presets the user can select. from.

Parameters

[out]

presets

The vector list containing the names of presets that the user can select

Returns

Return true if successful, or false if there are no presets to choose from

GetActivePreset()

virtual int GetActivePreset ( )

inlinevirtual

Get the index of the current preset.

Returns

Index number of the current preset

IsLocked()

virtual bool IsLocked ( )

inlinevirtual

Check if the add-on is locked to the current preset.

Returns

True if locked to the current preset

PrevPreset()

virtual bool PrevPreset ( )

inlinevirtual

Load the previous visualization preset.

Returns

Return true if the previous preset was loaded

NextPreset()

virtual bool NextPreset ( )

inlinevirtual

Load the next visualization preset.

Returns

Return true if the next preset was loaded

LoadPreset()

virtual bool LoadPreset ( int  select )

inlinevirtual

Load a visualization preset.

This function is called after a new preset is selected.

Parameters

[in]

select

Preset index to use

Returns

Return true if the preset is loaded

RandomPreset()

virtual bool RandomPreset ( )

inlinevirtual

Switch to a new random preset.

Returns

Return true if a random preset was loaded

LockPreset()

virtual bool LockPreset ( bool  lockUnlock )

inlinevirtual

Lock the current visualization preset, preventing it from changing.

Parameters

[in]

lockUnlock

If set to true, the preset should be locked

Returns

Return true if the current preset is locked

RatePreset()

virtual bool RatePreset ( bool  plusMinus )

inlinevirtual

Used to increase/decrease the visualization preset rating.

Parameters

[in]

plusMinus

If set to true the rating is increased, otherwise decreased

Returns

Return true if the rating is modified

UpdateAlbumart()

virtual bool UpdateAlbumart ( std::string  albumart )

inlinevirtual

Inform the visualization of the current album art image.

Parameters

[in]

albumart

Path to the current album art image

Returns

Return true if the image is used

UpdateTrack()

virtual bool UpdateTrack ( const kodi::addon::VisualizationTrack &  track )

inlinevirtual

Inform the visualization of the current track's tag information.

Parameters

[in]

track

Visualization track information structure

Returns

Return true if the track information is used

---

The following table contains values that can be set with class VisualizationTrack :

Name	Type	Set call	Get call
Title of the current song.	std::string	SetTitle	GetTitle
Artist names, as a single string	std::string	SetArtist	GetArtist
Album that the current song is from.	std::string	SetAlbum	GetAlbum
Album artist names, as a single string	std::string	SetAlbumArtist	GetAlbumArtist
The genre name from the music tag, if present	std::string	SetGenre	GetGenre
Duration of the current song, in seconds	int	SetDuration	GetDuration
Track number of the current song	int	SetTrack	GetTrack
Disc number of the current song stored in the ID tag info	int	SetDisc	GetDisc
Year that the current song was released	int	SetYear	GetYear
Lyrics of the current song, if available	std::string	SetLyrics	GetLyrics
The user-defined rating of the current song	int	SetRating	GetRating
Comment of the current song stored in the ID tag info	std::string	SetComment	GetComment

---

Example:

#include <kodi/addon-instance/Visualization.h>
 
class CMyVisualization : public kodi::addon::CInstanceVisualization
{
public:
  CMyVisualization(KODI_HANDLE instance, const std::string& version);
 
  ...
 
private:
  kodi::addon::VisualizationTrack m_runningTrack;
};
 
bool CMyVisualization::UpdateTrack(const kodi::addon::VisualizationTrack& track)
{
  m_runningTrack = track;
  return true;
}