Detailed Description

`Class: kodi::addon::CInstanceAudioEncoder`

Audio encoder add-on instance.
For audio encoders as binary add-ons. This class implements a way to handle the encode of given stream to a new format.

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

Here's an example on addon.xml:

<extension
  point="kodi.audioencoder"
  extension=".flac"
  library_@PLATFORM@="@LIBRARY_FILENAME@"/>

Description to audio encoder related addon.xml values:

Name	Description
`point`	Addon type specification At all addon types and for this kind always "kodi.audioencoder".
`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.

Here is a code example how this addon is used:

#include <kodi/addon-instance/AudioEncoder.h>
 
class ATTRIBUTE_HIDDEN CMyAudioEncoder : public kodi::addon::CInstanceAudioEncoder
{
public:
  CMyAudioEncoder(KODI_HANDLE instance, const std::string& kodiVersion)
    : kodi::addon::CInstanceAudioEncoder(instance, kodiVersion)
 
  bool Init(const std::string& filename, unsigned int filecache,
            int& channels, int& samplerate,
            int& bitspersample, int64_t& totaltime,
            int& bitrate, AEDataFormat& format,
            std::vector<AEChannel>& channellist) override;
  int Encode(int numBytesRead, const uint8_t* pbtStream) override;
  bool Finish() override; // Optional
};
 
CMyAudioEncoder::CMyAudioEncoder(KODI_HANDLE instance)
  : kodi::addon::CInstanceAudioEncoder(instance)
{
  ...
}
 
bool CMyAudioEncoder::Start(int inChannels,
                            int inRate,
                            int inBits,
                            const std::string& title,
                            const std::string& artist,
                            const std::string& albumartist,
                            const std::string& album,
                            const std::string& year,
                            const std::string& track,
                            const std::string& genre,
                            const std::string& comment,
                            int trackLength)
{
  ...
  return true;
}
 
int CMyAudioEncoder::Encode(int numBytesRead, const uint8_t* pbtStream)
{
  uint8_t* data = nullptr;
  int length = 0;
  ...
  kodi::addon::CInstanceAudioEncoder::Write(data, length);
 
  return 0;
}
 
 
bool CMyAudioEncoder::Finish()
{
  ...
  return true;
}
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  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_AUDIOENCODER)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my audio encoder instance");
    addonInstance = new CMyAudioEncoder(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

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

Function Documentation

◆ CInstanceAudioEncoder()

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

inlineexplicit

Audio encoder class constructor used to support multiple instances.

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 CMyAudioEncoder : public kodi::addon::CInstanceAudioEncoder
{
public:
  CMyAudioEncoder(KODI_HANDLE instance, const std::string& kodiVersion)
    : kodi::addon::CInstanceAudioEncoder(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 encoder instance");
  addonInstance = new CMyAudioEncoder(instance, version);
  return ADDON_STATUS_OK;
}

◆ Start()

virtual bool Start	(	int	inChannels,
		int	inRate,
		int	inBits,
		const std::string &	title,
		const std::string &	artist,
		const std::string &	albumartist,
		const std::string &	album,
		const std::string &	year,
		const std::string &	track,
		const std::string &	genre,
		const std::string &	comment,
		int	trackLength
	)

pure virtual

Start encoder (required)

Parameters

[in]	inChannels	Number of channels
[in]	inRate	Sample rate of input data
[in]	inBits	Bits per sample in input data
[in]	title	The title of the song
[in]	artist	The artist of the song
[in]	albumartist	The albumartist of the song
[in]	year	The year of the song
[in]	track	The track number of the song
[in]	genre	The genre of the song
[in]	comment	A comment to attach to the song
[in]	trackLength	Total track length in seconds

Returns: True on success, false on failure.

◆ Encode()

virtual int Encode	(	int	numBytesRead,
		const uint8_t *	pbtStream
	)

pure virtual

Encode a chunk of audio (required)

Parameters

[in]	numBytesRead	Number of bytes in input buffer
[in]	pbtStream	The input buffer

Returns: Number of bytes consumed

◆ Finish()

virtual bool Finish ( )

inlinevirtual

Finalize encoding (optional)

Returns: True on success, false on failure.

◆ Write()

int Write	(	const uint8_t *	data,
		int	length
	)

inline

Write block of data.

Parameters

[in]	data	Pointer to the array of elements to be written
[in]	length	Size in bytes to be written.

Returns: The total number of bytes successfully written is returned.

Remarks: Only called from addon itself.

◆ Seek()

int64_t Seek	(	int64_t	position,
		int	whence = `SEEK_SET`
	)

inline

Set the file's current position.

The whence argument is optional and defaults to SEEK_SET (0)

Parameters

[in] position The position that you want to seek to

[in]

whence

[optional] offset relative to
You can set the value of whence to one of three things:

Value	int	Description
SEEK_SET	0	position is relative to the beginning of the file. This is probably what you had in mind anyway, and is the most commonly used value for whence.
SEEK_CUR	1	position is relative to the current file pointer position. So, in effect, you can say, "Move to my current position plus 30 bytes," or, "move to my current position minus 20 bytes."
SEEK_END	2	position is relative to the end of the file. Just like SEEK_SET except from the other end of the file. Be sure to use negative values for offset if you want to back up from the end of the file, instead of going past the end into oblivion.

Returns: Returns the resulting offset location as measured in bytes from the beginning of the file. On error, the value -1 is returned.

Remarks: Only called from addon itself.