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"
    tags="true"
    library_@PLATFORM@="@LIBRARY_FILENAME@">
    <support>
      <extension name=".2sf">
        <description>30100</description>
        <icon>resources/file_format_music_sound.png</icon>
      </extension>
      <extension name=".mini2sf"/>
    </support>
  </extension>
  <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.
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.
<support><extension name="..." /></support>	The file extensions / styles supported by this addon.\nOptional can be with <description> and <icon>additional info added where used for list views in Kodi.
<support><mimetype name="..." /></support>	A stream URL mimetype where can be used to force to this addon.\nOptional can be with `<description> and <icon>additional info added where used for list views in Kodi.

---

Here is a code example how this addon is used:

#include <kodi/addon-instance/AudioDecoder.h>
 
class CMyAudioDecoder : public kodi::addon::CInstanceAudioDecoder
{
public:
  CMyAudioDecoder(const kodi::addon::IInstanceInfo& instance);
 
  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(const kodi::addon::IInstanceInfo& instance)
  : kodi::addon::CInstanceAudioDecoder(instance)
{
  ...
}
 
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 AUDIODECODER_READ_SUCCESS;
}
 
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(const kodi::addon::IInstanceInfo& instance,
                              KODI_ADDON_INSTANCE_HDL& hdl) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  if (instance.IsType(ADDON_INSTANCE_AUDIODECODER))
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my audio decoder");
    hdl = new CMyAudioDecoder(instance);
    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.

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

Function Documentation

CInstanceAudioDecoder()

CInstanceAudioDecoder ( const kodi::addon::IInstanceInfo & instance )

inlineexplicit

Audio decoder class constructor used to support multiple instance types.

Parameters

[in]

instance

The instance value given to kodi::addon::CAddonBase::CreateInstance(...).

---

Here's example about the use of this:

class CMyAudioDecoder : public kodi::addon::CInstanceAudioDecoder
{
public:
  CMyAudioDecoder(KODI_HANDLE instance)
    : kodi::addon::CInstanceAudioDecoder(instance)
  {
     ...
  }
 
  ...
};
 
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  kodi::Log(ADDON_LOG_INFO, "Creating my audio decoder");
  hdl = new CMyAudioDecoder(instance);
  return ADDON_STATUS_OK;
}

SupportsFile()

virtual bool SupportsFile ( const std::string & filename )

inlinevirtual

Checks addon support given file path.

Parameters

[in]

filename

The file to read

Returns

true if successfully done and supported, otherwise false

Note

Optional to add, as default becomes true used.

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 stream, see enum AudioEngineChannel for available values

Returns

true if successfully done, otherwise false

ReadPCM()

virtual int ReadPCM ( uint8_t * buffer, size_t size, size_t & 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

Possible values are:

Value	enum	Description
0	AUDIODECODER_READ_SUCCESS	on success
-1	AUDIODECODER_READ_EOF	on end of stream
1	AUDIODECODER_READ_ERROR	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
Cover art by path	std::string	SetCoverArtByPath	GetCoverArtByPath
Cover art by memory	std::string	SetCoverArtByMem	GetCoverArtByMem

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

GetTrack()

static std::string GetTrack ( const std::string & name, const std::string & trackPath, int & track )

inlinestatic

Static auxiliary function to read the track number used from the given path.

If track number is not found in file name, the originally given file name is returned, track number then remains at "0".

Parameters

[in]	name	The value specified in addon.xml extension under name="???"
[in]	trackPath	The full path to evaluate
[out]	track	The track number read out in the path, 0 if not identified as a track path.

Returns

Path to the associated file