unaencoderapi.pas

Voice Commnucation Components for Delphi

(*
	----------------------------------------------

	  unaEncoderAPI.pas
	  Voice Communicator components version 2.5
	  API for external encoders/decoders

	----------------------------------------------
	  This source code cannot be used without
	  proper permission granted to you as a private
	  person or an entity by the Lake of Soft, Ltd

	  Visit http://lakeofsoft.com/ for details.

	  Copyright (c) 2001, 2007 Lake of Soft, Ltd
		     All rights reserved
	----------------------------------------------

	  created by:
		Lake, 21 Oct 2002

	  modified by:
		Lake, Oct-Nov 2002
		Lake, Jan-Oct 2003
		Lake, Mar-Oct 2005
		Lake, Apr 2007

	----------------------------------------------
*)

{$I unaDef.inc}
{$I unaBassDef.inc }

unit
  unaEncoderAPI;

{DP:UNIT
  Contains library API and wrapper classes for Blade/Lame MP3 encoders, Vorbis/Ogg libraries, BASS library.
  <BR><A HREF="http://bladeenc.mp3.no/">Blade MP3 Encoder</A>
  <BR><A HREF="http://www.mp3dev.org/">Lame MP3 Encoder</A>
  <BR><A HREF="http://www.xiph.org/ogg/vorbis/">Ogg/Vorbis library</A>
  <BR><A HREF="http://www.un4seen.com/">BASS library</A>
}

interface

uses
  Windows, unaTypes, unaClasses,
  unaBladeEncAPI, unaVorbisAPI, unaBassAPI, unaOpenH323PluginAPI;


// ============= una errors ========================

const
  UNA_ENCODER_ERR_NOT_SUPPORTED		   =	$10000003;
  UNA_ENCODER_ERR_CONFIG_REQUIRED	   =	$10000004;
  UNA_ENCODER_ERR_FEED_MORE_DATA	   =	$10000005;	// not an error

type
  UNA_ENCODER_ERR = int;

  // --  --
  {DP:METHOD
    Class event for data availabitity notification.
  }
  tUnaEncoderDataAvailableEvent = procedure (sender: tObject; data: pointer; size: unsigned; var copyToStream: bool) of object;

  //
  // -- unaAbstractEncoder --
  //

  {DP:CLASS
    Base abstract class for stream encoder/decoder.
  }
  unaAbstractEncoder = class
  private
    f_priority: integer;
    //
    f_outStream: unaMemoryStream;
    f_inStream: unaMemoryStream;
    f_lazyThread: unaThread;
    //
    f_onDA: tUnaEncoderDataAvailableEvent;
    f_gate: unaInProcessGate;
    //
    function get_priority(): integer;
    procedure set_priority(value: integer);
    //
    procedure _write();
    function get_availableDataSize(index: integer): unsigned;
  protected
    f_errorCode: UNA_ENCODER_ERR;
    f_configOK: bool;
    f_opened: bool;
    //
    f_inBuf: pointer;
    f_inBufSize: unsigned;
    f_outBuf: pointer;
    f_outBufSize: unsigned;
    f_outBufUsed: unsigned;
    f_inputChunkSize: unsigned;	// must be set by doSetup();
    //
    f_minOutputBufSize: unsigned;
    f_encodedDataSize: unsigned;
    //
    {DP:METHOD
    }
    function doDAEvent(data: pointer; size: unsigned): bool; virtual;
    {DP:METHOD
      Override this method to provide implementation of encoder configuration.
      <BR>Returns status code of encoder after config information provided with config parameter was applied.
    }
    function doSetConfig(config: pointer): UNA_ENCODER_ERR; virtual; abstract;
    {DP:METHOD
      Override this method to provide implementation of opening the encoder.
      <BR>Returns status code of encoder after it was opened.
    }
    function doOpen(): UNA_ENCODER_ERR; virtual; abstract;
    {DP:METHOD
      Override this method to provide implementation of closing the encoder.
      <BR>Returns status code of encoder after was closed.
    }
    function doClose(): UNA_ENCODER_ERR; virtual; abstract;
    {DP:METHOD
      Override this method to provide implementation of encoding the portion of data.
      <BR>Returns status code of encoding.
    }
    function doEncode(data: pointer; nBytes: unsigned; out bytesUsed: unsigned): UNA_ENCODER_ERR; virtual; abstract;
    //
    function enter(timeout: unsigned): bool;
    //
    function leave(): bool;
  public
    {DP:METHOD
      Creates an encoder with specified priority.
      <BR>priority has meaning whit lazyWrite() method only.
    }
    constructor create(priority: integer = THREAD_PRIORITY_NORMAL);
    procedure AfterConstruction(); override;
    procedure BeforeDestruction(); override;
    //
    {DP:METHOD
      Configures encoder with specific stream parameters.
    }
    function setConfig(config: pointer): UNA_ENCODER_ERR;
    {DP:METHOD
      Activates the encoder.
    }
    function open(): UNA_ENCODER_ERR;
    {DP:METHOD
      Deactivates the encoder.
    }
    function close(): UNA_ENCODER_ERR;
    {DP:METHOD
      Returns number of bytes produced by encoder.
      Encoded data is first sent to onDataAvailable() event (if handler is assigned).
      If this event has no handler assigned, or handler returns writeToStream = true,
      data is also written into ouput stream.
      <BR>Check errorCode property if 0 was returned.
      <BR>Do not mix lazyWrite() and encodeChunk() calls.
    }
    function encodeChunk(data: pointer; size: unsigned; lastOne: bool = false): unsigned;
    {DP:METHOD
      Encodes a chunk of data. Encoded data is copied into outBuf.
      Returns actual number of bytes produced by this function or zero if some error has occured.
      Writes encoded data into outBuf.
      Number of bytes written into outBuf will not exceed outBufSize (which could be less than required).
      This function does not call onDataAvailable() and does not write any data into output stream.
      Size parameter also used to return number of bytes used in input buffer. 
      <BR>Check errorCode property if 0 was returned.
      <BR>Do not mix lazyWrite() and encodeChunkInPlace() calls.
    }
    function encodeChunkInPlace(data: pointer; var size: unsigned; outBuf: pointer; outBufSize: unsigned): unsigned;
    {DP:METHOD
      Returns immediately after copying the data from buffer.
      <BR>Uses internal thread to feed the encoder.
      <BR>Do not mix lazyWrite() and encodeChunk() calls.
    }
    procedure lazyWrite(buf: pointer; size: unsigned);
    {DP:METHOD
      Reads data from the encoder output buffer.
      <BR>Returns number of bytes read from output buffer.
    }
    function read(buf: pointer; size: unsigned = 0): unsigned;
    {DP:METHOD
      Returns number of bytes available to read from output stream.
    }
    property availableOutputDataSize: unsigned index 0 read get_availableDataSize;
    {DP:METHOD
      Returns number of bytes awaiting to be processed in the input stream.
    }
    property availableInputDataSize: unsigned index 1 read get_availableDataSize;
    {DP:METHOD
      Returns number of bytes awaiting to be processed in the input stream of lazy thread.
    }
    property availableLazyDataSize: unsigned index 2 read get_availableDataSize;
    {DP:METHOD
      Size of input chunk in bytes.
    }
    property inputChunkSize: unsigned read f_inputChunkSize;
    {DP:METHOD
      Number of bytes encoded so far.
    }
    property encodedDataSize: unsigned read f_encodedDataSize;
    {DP:METHOD
      Encoder status code.
    }
    property errorCode: UNA_ENCODER_ERR read f_errorCode;
    {DP:METHOD
      Priority of encoder thread.
      Has meaning only when you are using lazyWrite().
    }
    property priority: integer read get_priority write set_priority;
    {DP:METHOD
      Can be fired from internal thread, so do not use VCL calls in the handler.
      If you assign a handler for this event, and will not change the copyToStream parameter, data will not be copied into output stream.
    }
    property onDataAvailable: tUnaEncoderDataAvailableEvent read f_onDA write f_onDA;
  end;


// =========================== BLADE MP3 ENCODER ==========================

  //
  // -- unaBladeMp3Enc --
  //

  {DP:CLASS
    Provides access to Blade MP3 encoder.
    <BR>Requires Blade library DLL (BladeEnc.dll)
  }
  unaBladeMp3Enc = class(unaAbstractEncoder)
  private
    f_bladeProc: tBladeLibrary_proc;
  protected
    f_dllPathAndName: string;
    f_version: PBE_VERSION;
    //
    f_stream: HBE_STREAM;
    //
    {DP:METHOD
      Loads Blade encoder DLL into process memory.
    }
    function loadDLL(): int; virtual;
    {DP:METHOD
      Unloads Blade encoder DLL from process memory.
    }
    function unloadDLL(): int; virtual;
    //
    {DP:METHOD
      Returns version of loaded Blade encoder.
    }
    procedure getVersion(); virtual;
    //
    {DP:METHOD
      Opens Blade encoder.
    }
    function doOpen(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Configures Blade encoder.
    }
    function doSetConfig(config: pointer): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Closes Blade encoder.
    }
    function doClose(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Encodes a chunk of data.
    }
    function doEncode(data: pointer; nBytes: unsigned; out bytesUsed: unsigned): UNA_ENCODER_ERR; override;
  public
    {DP:METHOD
      Creates Blade encoder API provider.
    }
    constructor create(const dllPathAndName: string = ''; priority: integer = THREAD_PRIORITY_NORMAL);
    procedure AfterConstruction(); override;
    procedure BeforeDestruction(); override;
    {DP:METHOD
      Version of Blade encoder.
    }
    property version: PBE_VERSION read f_version;
  end;


// =========================== LAME MP3 ENCODER ==========================

  //
  // -- unaLameMp3Enc --
  //

  {DP:CLASS
    Provides access to Lame MP3 encoder.
    <BR>Requires Lame library DLL (lame_enc.dll)
  }
  unaLameMp3Enc = class(unaBladeMp3Enc)
  private
    f_lameProc: tLameLibrary_proc;
  protected
    {DP:METHOD
      Loads Lame encoder DLL into process memory.
    }
    function loadDLL(): int; override;
    {DP:METHOD
      Unloads Lame encoder DLL into process memory.
    }
    function unloadDLL(): int; override;
    {DP:METHOD
      Returns version of loaded Lame encoder.
    }
    procedure getVersion(); override;
    //
    {DP:METHOD
      Configures Lame encoder.
    }
    function doSetConfig(config: pointer): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Closes Lame encoder.
    }
    function doClose(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Encodes a chunk of data.
    }
    function doEncode(data: pointer; nBytes: unsigned; out bytesUsed: unsigned): UNA_ENCODER_ERR; override;
  end;


// =========================== VORBIS ENCODER/DECODER ==========================

  // --  --
  tVorbisEncodeMethodEnum = (vemABR, vemVBR, vemRateManage);

  // --  --
  pVorbisSetup = ^tVorbisSetup;
  tVorbisSetup = packed record
    //
    r_numOfChannels: byte;	// 1 - monophonic; 2 - stereo; 3 - 1d-surround; 4 - quadraphonic surround; 5 - five-channel surround; 5 - 5,1 surround
    r_samplingRate: unsigned;	// from 8000 up to 192000
    //
    case r_encodeMethod: tVorbisEncodeMethodEnum of

      vemABR:
	(r_min_bitrate: int;	// all bitrates are from about 48000 up to 360000 or -1
	 r_normal_bitrate: int;
	 r_max_bitrate: int);

      vemVBR:
	(r_quality: single);		// from -0.9999 (lowest) up to 1.0

      vemRateManage:
	(r_manage_minBitrate: int;
	 r_manage_normalBitrate: int;
	 r_manage_maxBitrate: int;
	 r_manage_mode: int);		// see OV_ECTL_RATEMANAGE_XXXX
  end;


  //
  // -- unaVorbisAbstract --
  //
  {DP:CLASS
    Provides access to Vorbis library API.
  }
  unaVorbisAbstract = class(unaAbstractEncoder)
  private
    f_vi: tVorbis_info;
    f_vc: tVorbis_comment;
    f_vd: tVorbis_dsp_state;
    f_vb: tVorbis_block;
    //
    f_popPacketBuf: pointer;
    f_popPacketBufSize: unsigned;
    //
    function get_vb(): pVorbis_block;
    function get_vc(): pVorbis_comment;
    function get_vd(): pVorbis_dsp_state;
    function get_vi(): pVorbis_info;
  protected
    f_vorbisDllPathAndName: string;
    f_version: int;
    //
    {DP:METHOD
      Loads Vorbis DLL into process memory.
    }
    function loadDLL(): int; virtual;
    {DP:METHOD
      Unloads Vorbis DLL from process memory.
    }
    function unloadDLL(): int; virtual;
    {DP:METHOD
      Closes Vorbis library.
    }
    function doClose(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Pops Ogg packet (if any) from output stream.
      NOTE: All packets share same buffer, so only one packet at a time must be popped.
    }
    function doPopPacket(var packet: tOgg_packet): bool;
  public
    {DP:METHOD
      Creates Vorbis library API provider.
    }
    constructor create(const vorbisDll: string = ''; priority: integer = THREAD_PRIORITY_NORMAL);
    procedure AfterConstruction(); override;
    procedure BeforeDestruction(); override;
    {DP:METHOD
      same as doPopPacket();
    }
    function popPacket(var packet: tOgg_packet): bool;
    {DP:METHOD
      Version of Vorbis library.
    }
    property version: int read f_version;
    //
    property vi: pVorbis_info read get_vi;
    property vc: pVorbis_comment read get_vc;
    property vd: pVorbis_dsp_state read get_vd;
    property vb: pVorbis_block read get_vb;
  end;


  //
  // -- unaVorbisEnc --
  //

  {DP:CLASS
    Provides interface of Vorbis/Ogg stream encoding.
    <BR>Requires Vorbis/Ogg libraries DLLs (ogg.dll, vorbis.dll and vorbisenc.dll)
  }
  unaVorbisEnc = class(unaVorbisAbstract)
  private
    f_vorbisEncDllPathAndName: string;
    f_isFirstChunk: bool;
    f_isLastChunk: bool;
    //
    procedure vorbis_analyze();
    procedure pushPacket(const packet: tOgg_packet);
  protected
    {DP:METHOD
      Loads Vorbis encoder DLLs into process memory.
    }
    function loadDLL(): int; override;
    {DP:METHOD
      Unloads Vorbis DLLs from process memory.
    }
    function unloadDLL(): int; override;
    {DP:METHOD
      Opens Vorbis encoder.
    }
    function doOpen(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Configures Vorbis encoder.
    }
    function doSetConfig(config: pointer): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Closes Vorbis encoder.
    }
    function doClose(): UNA_ENCODER_ERR; override;
    {DP:METHOD
      Encodes a chunk of data.
    }
    function doEncode(data: pointer; nBytes: unsigned; out bytesUsed: unsigned): UNA_ENCODER_ERR; override;
  public
    {DP:METHOD
      Creates Vorbis/Ogg encoder interface.
    }
    constructor create(const vorbisDll: string = ''; const vorbisEncDll: string = ''; priority: integer = THREAD_PRIORITY_NORMAL);
    {DP:METHOD
      Adds comments to Vorbis stream header.
    }
    procedure vorbis_addComment(const tagName, tagValue: string);
  end;