Audio Decoder

Detailed Description

Class: kodi::addon::CInstanceAudioDecoder

Audio decoder add-on instance

For audio decoders as binary add-ons. This class implements a way to handle special types of audio files.

The add-on handles loading of the source file and outputting the audio stream for consumption by the player.

The addon.xml defines the capabilities of this add-on.

Note

The option to have multiple instances is possible with audio-decoder add-ons. This is useful, since some playback engines are riddled by global variables, making decoding of multiple streams using the same instance impossible.

---

Here's an example on addon.xml:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="audiodecoder.myspecialnamefor"
  version="1.0.0"
  name="My special audio decoder addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="kodi.audiodecoder"
    name="2sf"
    extension=".2sf|.mini2sf"
    tags="true"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My audio decoder addon addon</summary>
    <description lang="en_GB">My audio decoder addon description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Description to audio decoder related addon.xml values:

Name	Description
point	Addon type specification At all addon types and for this kind always "kodi.audiodecoder".
library_@PLATFORM@	Sets the used library name, which is automatically set by cmake at addon build.
extension	The file extensions / styles supported by this addon.
mimetype	A stream URL mimetype where can be used to force to this addon.
name	The name of the decoder used in Kodi for display.
tags	Boolean to point out that addon can bring own information to replayed file, if false only the file name is used as info. If true, CInstanceAudioDecoder::ReadTag is used and must be implemented.
tracks	Boolean to in inform one file can contains several different streams.

---

Here is a code example how this addon is used:

#include <kodi/addon-instance/AudioDecoder.h>
 
class CMyAudioDecoder : public kodi::addon::CInstanceAudioDecoder
{
public:
  CMyAudioDecoder(KODI_HANDLE instance, const std::string& version);
 
  bool Init(const std::string& filename, unsigned int filecache,
            int& channels, int& samplerate,
            int& bitspersample, int64_t& totaltime,
            int& bitrate, AudioEngineDataFormat& format,
            std::vector<AudioEngineChannel>& channellist) override;
  int ReadPCM(uint8_t* buffer, int size, int& actualsize) override;
};
 
CMyAudioDecoder::CMyAudioDecoder(KODI_HANDLE instance, const std::string& version)
  : kodi::addon::CInstanceAudioDecoder(instance, version)
{
  ...
}
 
bool CMyAudioDecoder::Init(const std::string& filename, unsigned int filecache,
                           int& channels, int& samplerate,
                           int& bitspersample, int64_t& totaltime,
                           int& bitrate, AudioEngineDataFormat& format,
                           std::vector<AudioEngineChannel>& channellist)
{
  ...
  return true;
}
 
int CMyAudioDecoder::ReadPCM(uint8_t* buffer, int size, int& actualsize)
{
  ...
  return 0;
}
 
 
//----------------------------------------------------------------------
 
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_AUDIODECODER)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my audio decoder");
    addonInstance = new CMyAudioDecoder(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

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

Modules
	Definitions, structures and enumerators
	Audio decoder add-on instance definition values All audio decoder functions associated data structures.

Function Documentation

CInstanceAudioDecoder()

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

inlineexplicit

Audio decoder 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 CMyAudioDecoder : public kodi::addon::CInstanceAudioDecoder
{
public:
  CMyAudioDecoder(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 audio decoder");
  addonInstance = new CMyAudioDecoder(instance, version);
  return ADDON_STATUS_OK;
}

Init()

virtual bool Init ( const std::string &  filename, unsigned int  filecache, int &  channels, int &  samplerate, int &  bitspersample, int64_t &  totaltime, int &  bitrate, AudioEngineDataFormat &  format, std::vector< AudioEngineChannel > &  channellist  )

pure virtual

Initialize a decoder.

Parameters

[in]	filename	The file to read
[in]	filecache	The file cache size
[out]	channels	Number of channels in output stream
[out]	samplerate	Samplerate of output stream
[out]	bitspersample	Bits per sample in output stream
[out]	totaltime	Total time for stream
[out]	bitrate	Average bitrate of input stream
[out]	format	Data format for output stream, see class AudioEngineFormat for available values
[out]	channellist	Channel mapping for output streamm, see enum AudioEngineChannel for available values

Returns

true if successfully done, otherwise false

ReadPCM()

virtual int ReadPCM ( uint8_t *  buffer, int  size, int &  actualsize  )

pure virtual

Produce some noise.

Parameters

[in]	buffer	Output buffer
[in]	size	Size of output buffer
[out]	actualsize	Actual number of bytes written to output buffer

Returns

Return with following possible values:

Value	Description
0	on success
-1	on end of stream
1	on failure

Seek()

virtual int64_t Seek ( int64_t  time )

inlinevirtual

Seek in output stream.

Parameters

[in]

time

Time position to seek to in milliseconds

Returns

Time position seek ended up on

ReadTag()

virtual bool ReadTag ( const std::string &  file, kodi::addon::AudioDecoderInfoTag &  tag  )

inlinevirtual

Read tag of a file.

Parameters

[in]	file	File to read tag for
[out]	tag	Information tag about

Returns

True on success, false on failure

---

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

Name	Type	Set call	Get call
Title	std::string	SetTitle	GetTitle
Artist	std::string	SetArtist	GetArtist
Album	std::string	SetAlbum	GetAlbum
Album artist	std::string	SetAlbumArtist	GetAlbumArtist
Media type	std::string	SetMediaType	GetMediaType
Genre	std::string	SetGenre	GetGenre
Duration	int	SetDuration	GetDuration
Track number	int	SetTrack	GetTrack
Disc number	int	SetDisc	GetDisc
Disc subtitle name	std::string	SetDiscSubtitle	GetDiscSubtitle
Disc total amount	int	SetDiscTotal	GetDiscTotal
Release date	std::string	SetReleaseDate	GetReleaseDate
Lyrics	std::string	SetLyrics	GetLyrics
Samplerate	int	SetSamplerate	GetSamplerate
Channels amount	int	SetChannels	GetChannels
Bitrate	int	SetBitrate	GetBitrate
Comment text	std::string	SetComment	GetComment

TrackCount()

virtual int TrackCount ( const std::string &  file )

inlinevirtual

Get number of tracks in a file.

Parameters

[in]

file

File to read tag for

Returns

Number of tracks in file