Visualization

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. More...

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.

Functions
	kodi::addon::CInstanceVisualization::CInstanceVisualization ()
	Visualization class constructor. More...
	kodi::addon::CInstanceVisualization::CInstanceVisualization (KODI_HANDLE instance, const std::string &kodiVersion="")
	Visualization class constructor used to support multiple instance types. More...
	kodi::addon::CInstanceVisualization::~CInstanceVisualization () override=default
	Destructor. More...
virtual bool	kodi::addon::CInstanceVisualization::Start (int channels, int samplesPerSec, int bitsPerSample, std::string songName)
	Used to notify the visualization that a new song has been started. More...
virtual void	kodi::addon::CInstanceVisualization::Stop ()
	Used to inform the visualization that the rendering control was stopped. More...
virtual void	kodi::addon::CInstanceVisualization::AudioData (const float *audioData, int audioDataLength, float *freqData, int freqDataLength)
	Pass audio data to the visualization. More...
virtual bool	kodi::addon::CInstanceVisualization::IsDirty ()
	Used to inform Kodi that the rendered region is dirty and need an update. More...
virtual void	kodi::addon::CInstanceVisualization::Render ()
	Used to indicate when the add-on should render. More...
virtual void	kodi::addon::CInstanceVisualization::GetInfo (bool &wantsFreq, int &syncDelay)
	Used to get the number of buffers from the current visualization. More...
virtual bool	kodi::addon::CInstanceVisualization::GetPresets (std::vector< std::string > &presets)
	Used to get a list of visualization presets the user can select. from. More...
virtual int	kodi::addon::CInstanceVisualization::GetActivePreset ()
	Get the index of the current preset. More...
virtual bool	kodi::addon::CInstanceVisualization::IsLocked ()
	Check if the add-on is locked to the current preset. More...
virtual bool	kodi::addon::CInstanceVisualization::PrevPreset ()
	Load the previous visualization preset. More...
virtual bool	kodi::addon::CInstanceVisualization::NextPreset ()
	Load the next visualization preset. More...
virtual bool	kodi::addon::CInstanceVisualization::LoadPreset (int select)
	Load a visualization preset. More...
virtual bool	kodi::addon::CInstanceVisualization::RandomPreset ()
	Switch to a new random preset. More...
virtual bool	kodi::addon::CInstanceVisualization::LockPreset (bool lockUnlock)
	Lock the current visualization preset, preventing it from changing. More...
virtual bool	kodi::addon::CInstanceVisualization::RatePreset (bool plusMinus)
	Used to increase/decrease the visualization preset rating. More...
virtual bool	kodi::addon::CInstanceVisualization::UpdateAlbumart (std::string albumart)
	Inform the visualization of the current album art image. More...
virtual bool	kodi::addon::CInstanceVisualization::UpdateTrack (const kodi::addon::VisualizationTrack &track)
	Inform the visualization of the current track's tag information. More...

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.

Function Documentation

AudioData()

virtual void kodi::addon::CInstanceVisualization::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.

CInstanceVisualization() [1/2]

kodi::addon::CInstanceVisualization::CInstanceVisualization ( )

inline

Visualization class constructor.

Used by an add-on that only supports visualizations.

CInstanceVisualization() [2/2]

kodi::addon::CInstanceVisualization::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;
}

GetActivePreset()

virtual int kodi::addon::CInstanceVisualization::GetActivePreset ( )

inlinevirtual

Get the index of the current preset.

Returns

Index number of the current preset

GetInfo()

virtual void kodi::addon::CInstanceVisualization::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 kodi::addon::CInstanceVisualization::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

IsDirty()

virtual bool kodi::addon::CInstanceVisualization::IsDirty ( )

inlinevirtual

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

Returns

True if dirty

IsLocked()

virtual bool kodi::addon::CInstanceVisualization::IsLocked ( )

inlinevirtual

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

Returns

True if locked to the current preset

LoadPreset()

virtual bool kodi::addon::CInstanceVisualization::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

LockPreset()

virtual bool kodi::addon::CInstanceVisualization::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

NextPreset()

virtual bool kodi::addon::CInstanceVisualization::NextPreset ( )

inlinevirtual

Load the next visualization preset.

Returns

Return true if the next preset was loaded

PrevPreset()

virtual bool kodi::addon::CInstanceVisualization::PrevPreset ( )

inlinevirtual

Load the previous visualization preset.

Returns

Return true if the previous preset was loaded

RandomPreset()

virtual bool kodi::addon::CInstanceVisualization::RandomPreset ( )

inlinevirtual

Switch to a new random preset.

Returns

Return true if a random preset was loaded

RatePreset()

virtual bool kodi::addon::CInstanceVisualization::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

Render()

virtual void kodi::addon::CInstanceVisualization::Render ( void  )

inlinevirtual

Used to indicate when the add-on should render.

Start()

virtual bool kodi::addon::CInstanceVisualization::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 kodi::addon::CInstanceVisualization::Stop ( )

inlinevirtual

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

UpdateAlbumart()

virtual bool kodi::addon::CInstanceVisualization::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 kodi::addon::CInstanceVisualization::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;
}

~CInstanceVisualization()

kodi::addon::CInstanceVisualization::~CInstanceVisualization ( )

overridedefault

Destructor.