MP4 Stream Editor SDK - Plugin functions and procedures

MP4 Stream Editor Plugin entry points

Init(InitInfo: TInitInfo): TPluginInit;

Config: Boolean;

Activate(var Stream: TBassStreamItem; DSPPriority: Integer): Boolean;

DSPProcess(DSPHandle: HDSP; Channel: DWORD; Buffer: PSample; Length: DWORD; var User: DWORD);

VisSetup(var Stream: TBassStreamItem): Boolean;

VisOnClick(Button: TMouseButton; Width, Height, X, Y: Integer);

Status: String;

Deactivate(var Stream: TBassStreamItem): Boolean;

FreePlugin: Boolean;

p_Init = function(InitInfo: TInitInfo): TPluginInit; stdcall;

Description: When the plugin folder is enumerated Init() is called

Parameters:

InitInfo:

Initialization arguments

type
 TInitInfo = record
  ExeName: String;		//* Path and filename to MP3SE.exe
  PluginFolder: String;	//* DLL's location
  MainWindowHandle: HWND;	//* MP3SE's main form handle
 end;

Return value:

Plugin's response:

type
  TPluginInit = record
   PluginType: Word;	//* Combination of Plugin ID types
   PluginName: PChar;	//* Name of the plugin (Try to keep it less then 18 chars)
   InitOK: Boolean;	//* Plugin initialization was successfull
  end;

Remarks:

See also: FreePlugin, Status, MP3SEFuncsInit()

:: Top ::

p_Config = function: Boolean; stdcall;

Description: Configure plugin. Could be called even if active!

Parameters:

none

Return value:

False if there was an error

Remarks: Config() could be called anytime! The form should not be Modal type! Use TForm.Show;

See also: Status, MP3SEFuncsInit()

:: Top ::

p_Activate = function(var Stream: TBassStreamItem; DSPPriority: Integer): Boolean; stdcall;

Description: If initialization completed succesfully, when user starts the plugin (activates) Process is executed.
If plugin is of type DSP you should check and set parameters according to stream here.

Parameters:

var Stream:

type
  TBassStreamItem = record
    Name: String;                           //* FileName and path
    Opened: Boolean;                        //* Opened in MDIChildwin
    Selected: Boolean;                      //* Obsolete
    FreeIt: Boolean;                        //* Remove this stream as soon as possible
    CloseIt: Boolean;                       //* If Opened close stream as soon as possible
    sType: String;                          //* Type [PCM,MPG,URL,OGG,WMA,TAG,MOD,CDA,N/A]
    MPEGH: TMP3StreamHeader;                //* First frame or info if not MPEG
    Channel: Cardinal;                      //* Bass channel handle
    ChannelVol: Integer;                    //* Volume
    SyncEnd: Cardinal;                      //* Sync when play reaches end
    SyncFade: Cardinal;                     //* Fade Sync (pos := playtime - crossfade length)
    DSPs: Array[Byte] of TStreamDSPs;       //* DSPs set
    PlayTime: Int64;                        //* Playtime in ms
    Bits: Byte;                             //* Bits 8 or 16
    Playing: TPlayListStatus;               //* (plStoped, plPlaying, plPaused, plRecording)
    PlayingSel: Boolean;                    //* Playing selection
    Length: Int64;                          //* MPEG frame count or ~length (0.026s per frame)
    FrameBitRatesL: Boolean;                //* MPEG frames bitrates loaded
    FrameSize: Integer;                     //* CBR: frame sizes VBR: average frame size
    FrameVBR: Boolean;                      //* Stream is a VBR MPEG
    GfxZoom_StartPos: Double;               //* Sample zoom start
    GfxZoom_EndPos: Double;                 //* Sample zoom end
    GfxZoom: Double;                        //* Sample zoom
    Gfx_Pos: Integer;                       //* Sample position
    SelStart: Int64;                        //* Selection start in MPEG frames
    SelEnd: Int64;                          //* Selection end in MPEG frames
    SampleData: Array of Byte;              //* SESC (mono, may be stereo in the future)
    FrameBitRates: Array of Smallint;       //* MPEG frames bitrates
    ID3v1_Touched: Boolean;                 //* ID3v1 touched
    ID3v1_Found : Boolean;                  //* ID3v1 exists
    ID3v2_Touched: Boolean;                 //* ID3v2 touched
    ID3v2_Picture: String;                  //* ID3v2 Picture filename extracted in /Temp/
    ID3v2_PictureCaption: String;           //* ID3v2 Picture text
    ID3v2_Found : Boolean;                  //* ID3v2 exists
    myTag: Tid3v2Tag;                       //* ID3v1 Tag
    myTagv1: Tid3Tag;                       //* ID3v2 Tag
    PanelD3DHandle: HWND;                   //* 3DPanel Handle pass to Direct3D9.CreateDevice()
    RenderProc: t_RenderProc;               //* Rendering process (must be faster than 250ms)
    CustomRenderProc: Boolean;		  //* True if using custom process for rendering
    g_pd3dDevice: IDirect3DDevice9;	  //* D3D rendering device if Opened
    CustomD3DDevice: Boolean;		  //* Completly custom drawing
    vb_Coords: IDirect3DVertexBuffer9;      //* D3D coords vertexes
    vb_SD: IDirect3DVertexBuffer9;          //* D3D sample vertexes
    vb_BR: IDirect3DVertexBuffer9;          //* D3D bit rates vertexes
    vb_SD_middle: IDirect3DVertexBuffer9;   //* D3D middle 0 line vertexes
    vb_Cursor: IDirect3DVertexBuffer9;      //* D3D playpos vertexes
    vb_SelectionBack: IDirect3DVertexBuffer9; //* D3D selection back vertexes
    vb_Selection: IDirect3DVertexBuffer9;   //* D3D selection front vertexes
    vb_Blur: IDirect3DVertexBuffer9;        //* D3D blur vertexes (disabled)
    matWorld: TD3DMatrix;                   //* D3D World matrix
    matRotSD: TD3DMatrix;                   //* D3D Startup rotation matrix
    matrixSD_Amplitude: Single;             //* D3D Amplitude deformation matrix
    vc_SD: Integer;                         //* Sample vertex count
    vc_BR: Integer;                         //* Bit rates vertex count
    vc_Coords: Integer;                     //* Coords vertex count
    StartupAnim: Boolean;                   //* Rotation anim is on
    StartupAnimAngle: Single;               //* Rotation anim current angle
    Rendering: Boolean;                     //* Frame rendering is in progress (should be False)
    ShowBitRates: Boolean;                  //* Showing bit rates not samples
  end;

DSPPriority:

DSP's priority in the DSP chain. Low < 0 < High

Return value:

False if there was an error. Set Status.Active accordingly.

Remarks: Only change Stream parameters only if you now what you are doing!

See also: Status, MP3SEFuncsInit()

:: Top ::

p_DSPProcess = procedure(DSPHandle: HDSP; Channel: DWORD; Buffer: PSample; Length: DWORD; var User: DWORD); stdcall;

Description: The DSPProcess is directly called by BASS's DSPPROC callback. The floating-point sample data values range from -1 to 1 and it's not clipped to this range until output, so it's very possible that DSPProcess callback function calls could receive data beyond this range.
See BASS's docs about DSPPROC callbacks

Parameters:	DSPHandle	The DSP handle
	Channel:	Bass Channel that the DSP is being applied to
	Buffer:	The buffer to apply the DSP to. The sample data is in standard Windows PCM format 32-bit floating-point samples range from -1 to 1 (not clipped, so can actually be outside this range). There may be cases when it's in 8-bit unsigned or 16-bit signed.
	Length:	The number of BYTES to process
	var User:	The user instance data given when BASS_ChannelSetDSP() was called

Return value:

In case there was a serious error set Status to MP3SE_PLUGIN_STATUS_FAILED. This will always trigger the Deactivate() procedure.

Remarks: A DSP function should obviously be as quick as possible... playing streams, MOD musics and other DSP functions can not be processed until it has finished.

See also: Status, Bass

:: Top ::

p_VisSetup = function(var Stream: TBassStreamItem): Boolean; stdcall;

Description: Needed in visualisation plugins. Initializes D3D scene.
When using TBassStreamItem.CustomD3DDevice and using the 3D panel, you can check the .Visible property of the 3D panel (TBassStreamItem.PanelD3DHandle) for a little help to render the frame or not. Obviously if the panel is not visible there's no need to draw the frame.

Parameters:

Stream: TBassStreamItem

Return value:

False if there was an error

Remarks: This function must exist if plugin is of type MP3SE_PLUGIN_VIS!

See also: Process, MP3SEFuncsInit()

:: Top ::

p_VisOnClick = procedure(Button: TMouseButton; Width, Height, X, Y: Integer): Boolean; stdcall;

Description: Needed in visualisation plugins. The procedure is called when the user clicks on the 3D panel.

Parameters:	Button: Mouse button clicked
	Width, Height: 3D panel's width and height
	X, Y: Mouse position when clicked

Return value:

None

Remarks: This function must exist if plugin is of type MP3SE_PLUGIN_VIS!

See also: Process, MP3SEFuncsInit()

:: Top ::

p_Status = function: TPluginStatus; stdcall;

Description: Plugin's status and also the response shown to the user.

Parameters:

none

Return value:

type
  TPluginStatus = record	    //* Plugin status descriptor
    Active: Boolean;	    //* Plugin is active (working)
    Status: String;	    //* The string displayed to the user or one of the following:
  end;

MP3SE_PLUGIN_STATUS_FAILED
MP3SE_PLUGIN_STATUS_OK
MP3SE_PLUGIN_STATUS_FREED

Remarks: Status is called periodically (~every 250ms).

See also: MP3SEFuncsInit()

:: Top ::

p_Deactivate = function(var Stream: TBassStreamItem): Boolean; stdcall;

Description: Deactivate plugin.

Parameters:

Stream: TBassStreamItem

Return value:

False if there was an error

Remarks: Set Status.Active to FALSE accordingly!

See also: Process, MP3SEFuncsInit()

:: Top ::

p_FreePlugin = function: Boolean; stdcall;

Description: Free plugin's resources.

Parameters:

none

Return value:

False if there was an error

Remarks: Set Status to MP3SE_PLUGIN_STATUS_FREED accordingly!

See also: Init, MP3SEFuncsInit()