Main Engine Interface
[Flix Engine API]


Detailed Description

LINUX


Enumerations

enum  FE2_ExportedVideoType {
  ExportSWF3To6Video,
  ExportSWF7PlusVideo,
  ExportSWFVectorVideo,
  ExportFLVVideo
}
 Output file types for use in calls to Flix2_SetExportVideoType() and Flix2_GetExportVideoType(). More...
enum  FE2_EncState {
  EncStateIdle,
  EncStateRunning,
  EncStateQueued
}
 Encoder state returned by Flix2_GetEncoderState(). More...
enum  FE2_errno {
  ErrNone,
  ErrSys,
  ErrFileIO,
  ErrFileOpen,
  ErrFileDecode,
  ErrFileDecodeA,
  ErrFileDecodeV,
  ErrEncodeA,
  ErrEncodeV
}
 Flix engine error state returned by Flix2_Errno(). More...

Functions

on2sc Flix2_Create (FLIX2HANDLE *pFlix)
 Create a handle to the flix engine.
on2sc Flix2_CreateEx (FLIX2HANDLE *pFlix, const char *rpchost, int32_t timeout)
 Create a handle to the flix engine.
on2sc Flix2_Destroy (FLIX2HANDLE flix)
 Frees resources associated with a FLIX2HANDLE.
const char * Flix2_Version ()
 Returns the library version as a string.
const on2tcFlix2_Copyright ()
 Returns copyright information for this library as a string.
on2sc Flix2_SetOutputFile (FLIX2HANDLE flix, const on2tc *outputFile)
 Set the destination file for the encode session.
on2sc Flix2_GetOutputFile (const FLIX2HANDLE flix, on2tc *pOutputFile, int32_t *len)
 Get the destination file for the encode session.
on2sc Flix2_SetOverwriteExistingFiles (FLIX2HANDLE flix, const on2bool bOverwriteExistingFiles)
 Enable/disable overwriting of existing output files.
on2sc Flix2_GetOverwriteExistingFiles (const FLIX2HANDLE flix, on2bool *bpOverwriteExistingFiles)
 Retrieve the engine's current behavior regarding existing output files.
on2sc Flix2_SetExportAudio (FLIX2HANDLE flix, const on2bool bExportAudio)
 Enable/disable audio output in the current encoding session.
on2sc Flix2_GetExportAudio (const FLIX2HANDLE flix, on2bool *bpExportAudio)
 Retrieve the engine's current behavior regarding audio output.
on2sc Flix2_SetExportVideo (FLIX2HANDLE flix, const on2bool bExportVideo)
 Enable/disable video output in the current encoding session.
on2sc Flix2_GetExportVideo (const FLIX2HANDLE flix, on2bool *bpExportVideo)
 Retrieve the engine's current behavior regarding video output.
on2sc Flix2_SetExportVideoType (FLIX2HANDLE flix, const FE2_ExportedVideoType exportVideoType)
 Set the output file type.
on2sc Flix2_GetExportVideoType (const FLIX2HANDLE flix, FE2_ExportedVideoType *pExportVideoType)
 Retrieve the current output file type.
on2sc Flix2_SetInputFile (FLIX2HANDLE flix, const on2tc *inputFile)
 Set the source file for the encode session.
on2sc Flix2_GetInputFile (const FLIX2HANDLE flix, on2tc *pInputFile, int32_t *len)
 Get the source file for the encode session.
on2sc Flix2_GetSourceDuration (const FLIX2HANDLE flix, int32_t *duration)
 Get the duration, in milliseconds, of the source file.
on2sc Flix2_Encode (FLIX2HANDLE flix)
 Start encoding an output file.
on2sc Flix2_StopEncoding (FLIX2HANDLE flix)
 Cancel a running encoding session.
on2sc Flix2_Reset (FLIX2HANDLE flix)
 Reset the engine to its defaults.
on2sc Flix2_Validate (const FLIX2HANDLE flix)
 Validate the current encoder settings.
on2sc Flix2_IsEncoderRunning (const FLIX2HANDLE flix, on2bool *bpIsEncoderRunning)
 Check the status of an encode.
on2sc Flix2_GetEncoderState (const FLIX2HANDLE flix, FE2_EncState *pEncState)
 Retrieve the current state of the encoder.
on2sc Flix2_Errno (const FLIX2HANDLE flix, FE2_errno *flixerrno, int32_t *syserrno)
 Retrieve the current error state of the engine.

Enumeration Type Documentation

Encoder state returned by Flix2_GetEncoderState().

Enumerator:
EncStateIdle  the encoder is not running
EncStateRunning  the encoder is running
EncStateQueued  the session has been queued until space is available

Definition at line 101 of file flixengine2.h.

enum FE2_errno

Flix engine error state returned by Flix2_Errno().

Enumerator:
ErrNone  internal error was not set by the library
ErrSys  generic system error
ErrFileIO  generic file io error
ErrFileOpen  error opening file
ErrFileDecode 
ErrFileDecodeA 
ErrFileDecodeV 
ErrEncodeA 
ErrEncodeV 

Definition at line 108 of file flixengine2.h.

Output file types for use in calls to Flix2_SetExportVideoType() and Flix2_GetExportVideoType().

Deprecated:
Use the Muxer Interface. This enumeration will be removed in a future release. See also: Muxers.
Enumerator:
ExportSWF3To6Video 
ExportSWF7PlusVideo 
ExportSWFVectorVideo 
ExportFLVVideo 

Definition at line 93 of file flixengine2.h.


Function Documentation

const on2tc* Flix2_Copyright (  ) 

Returns copyright information for this library as a string.

on2sc Flix2_Create ( FLIX2HANDLE pFlix  ) 

Create a handle to the flix engine.

Initializes a FLIX2HANDLE for use in subsequent FLIXENGINE_API calls.

Parameters:
[out] pFlix storage location to receive the value of the created FLIX2HANDLE
Return values:
ON2_OK the engine successfully created and initialized a FLIX2HANDLE for use in FLIXENGINE_API functions.
ON2_INVALID_PARAMS should the precondition fail
ON2_NO_MEM memory could not be allocated for the FLIX2HANDLE
ON2_NET_ERROR the underlying communication layer failed. Call Flix2_Errno() for further information.
Common clnt_stat values in this case are:
  • RPC_SYSTEMERROR (12) errno=ECONNREFUSED (111) - connection to portmap on rpchost failed
  • RPC_UNKNOWNHOST (13) - rpchost name lookup failed
  • RPC_PROGNOTREGISTERED (15) - flixd is not registered with portmap on rpchost
For a complete listing see: rpc/clnt.h
Precondition:
pFlix is not NULL
Remarks:
Linux Only: Attempts first to connect portmap on localhost. Upon successful query of flixd's port, initiates a connection to the rpc server, flixd, which registers the encoding session. Failing either of these ON2_NET_ERROR is returned.

on2sc Flix2_CreateEx ( FLIX2HANDLE pFlix,
const char *  rpchost,
int32_t  timeout 
)

Create a handle to the flix engine.

Initializes a FLIX2HANDLE for use in subsequent FLIXENGINE_API calls.

Parameters:
[out] pFlix storage location to receive the value of the created FLIX2HANDLE
[in] rpchost hostname/IPv4 address where flixd is running NULL may be used in which case the connection will be attempted on localhost.
[in] timeout timeout in seconds for the underlying communication layer. Passing 0 will use the default, typically 25s.
Return values:
ON2_OK the engine successfully created and initialized a FLIX2HANDLE for use in FLIXENGINE_API functions.
ON2_INVALID_PARAMS should the precondition fail
ON2_NO_MEM memory could not be allocated for the FLIX2HANDLE
ON2_NET_ERROR the underlying communication layer failed. Call Flix2_Errno() for further information.
Common clnt_stat values in this case are:
  • RPC_SYSTEMERROR (12) errno=ECONNREFUSED (111) - connection to portmap on rpchost failed
  • RPC_UNKNOWNHOST (13) - rpchost name lookup failed
  • RPC_PROGNOTREGISTERED (15) - flixd is not registered with portmap on rpchost
For a complete listing see: rpc/clnt.h
Precondition:
pFlix is not NULL
Note:
Available on Linux only.
Remarks:
Attempts first to connect to portmap on rpchost. Upon successful query of flixd's port, initiates a connection to the rpc server, flixd, which registers the encoding session. Failing either of these ON2_NET_ERROR is returned.
rpchost may be given in the form:
 'server:port' 
to connect to flixd directly (if it was run with the --port option) to bypass the connection to portmap.

on2sc Flix2_Destroy ( FLIX2HANDLE  flix  ) 

Frees resources associated with a FLIX2HANDLE.

Parameters:
[in] flix FLIXHANDLE to be destroyed
Return values:
ON2_OK the engine successfully destroyed the handle
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
If an encoding session started with Flix2_Encode() is still running when this function is called. It will be stopped with Flix2_StopEncoding() before destroying the handle.

on2sc Flix2_Encode ( FLIX2HANDLE  flix  ) 

Start encoding an output file.

Encode the input file set in Flix2_SetInputFile() to the output file set in Flix2_SetOutputFile(), using the options set in the accessor functions or the engine defaults where applicable. Before starting the encode session, calls Flix2_Validate() to ensure the engine is ready to encode the input.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
Return values:
ON2_OK the engine successfully started the encode
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
<ON2_OK Flix2_Validate() failed / there was an error starting the encode session. Call Flix2_Errno() for more detail.
Precondition:
flix is not NULL
Note:
Linux Only: upon success flixd starts an encode thread on behalf of the FLIX2HANDLE.

Detail about the state of the encoder can be obtained by calling Flix2_IsEncoderRunning(), Flix2_GetEncoderState() or any of the Encoding Statistics functions

on2sc Flix2_Errno ( const FLIX2HANDLE  flix,
FE2_errno flixerrno,
int32_t syserrno 
)

Retrieve the current error state of the engine.

If an API call has returned an error, this function can be used to retrieve a more specific reason.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] flixerrno Storage location to receive the engine error
[out] syserrno Storage location to receive the system wide error
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
syserrno is the value of errno
If the last library status code was ON2_NET_ERROR flixerrno will be the RPC clnt_stat returned from same. enum clnt_stat values are defined in /usr/include/rpc/clnt.h.

on2sc Flix2_GetEncoderState ( const FLIX2HANDLE  flix,
FE2_EncState pEncState 
)

Retrieve the current state of the encoder.

If using the function to check for encode completion: when EncStateIdle is returned, the completion status can be obtained by calling Flix2_Errno()

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pEncState Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pEncState is not NULL
Remarks:
Linux Only: if flixd was run with the --max-sessions option, EncStateQueued may be returned if the number of concurrent encoding sessions was exceeded. This session will run in the order it was received when a slot becomes available

on2sc Flix2_GetExportAudio ( const FLIX2HANDLE  flix,
on2bool bpExportAudio 
)

Retrieve the engine's current behavior regarding audio output.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] bpExportAudio Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
bpExportAudio is not NULL
Note:
Default: on2true

on2sc Flix2_GetExportVideo ( const FLIX2HANDLE  flix,
on2bool bpExportVideo 
)

Retrieve the engine's current behavior regarding video output.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] bpExportVideo Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
bpExportVideo is not NULL
Note:
Default: on2true

on2sc Flix2_GetExportVideoType ( const FLIX2HANDLE  flix,
FE2_ExportedVideoType pExportVideoType 
)

Retrieve the current output file type.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pExportVideoType Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pExportVideoType is not NULL
Note:
Default: ExportFLVVideo
Deprecated:
Use the Muxer Interface. This function will be removed in a future release. See also: Muxers.

on2sc Flix2_GetInputFile ( const FLIX2HANDLE  flix,
on2tc pInputFile,
int32_t len 
)

Get the source file for the encode session.

Returns the input file name.
If pInputFile is NULL this function will return the size in bytes required to store the current input file in len, not including the null terminator.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pInputFile Storage location for the input file path
[in,out] len on input, the max number of bytes available in pInputFile. On return, the number of bytes used.
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
len is not NULL
Attention:
Currently only supported in C/C++

on2sc Flix2_GetOutputFile ( const FLIX2HANDLE  flix,
on2tc pOutputFile,
int32_t len 
)

Get the destination file for the encode session.

Returns the (possibly modified see Flix2_SetOutputFile()) output file name.
If pOutputFile is NULL this function will return the size in bytes required to store the current output file in len, not including the null terminator.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pOutputFile Storage location for the output file path
[in,out] len on input, the max number of bytes available in pOutputFile. On return, the number of bytes used.
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
len is not NULL
Attention:
Currently only supported in C/C++

on2sc Flix2_GetOverwriteExistingFiles ( const FLIX2HANDLE  flix,
on2bool bpOverwriteExistingFiles 
)

Retrieve the engine's current behavior regarding existing output files.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] bpOverwriteExistingFiles Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
bpOverwriteExistingFiles is not NULL
Note:
Default: on2false

on2sc Flix2_GetSourceDuration ( const FLIX2HANDLE  flix,
int32_t duration 
)

Get the duration, in milliseconds, of the source file.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] duration Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
duration is not NULL
Note:
This value is only valid after a call to Flix2_SetInputFile(). If the duration for the file could not be determined duration will be set to -1.

on2sc Flix2_IsEncoderRunning ( const FLIX2HANDLE  flix,
on2bool bpIsEncoderRunning 
)

Check the status of an encode.

Returns whether an encode session started with Flix2_Encode() is still running. If the function returns on2false the completion status can be obtained by calling Flix2_Errno()

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] bpIsEncoderRunning Storage location to receive the result
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL

on2sc Flix2_Reset ( FLIX2HANDLE  flix  ) 

Reset the engine to its defaults.

Resets all encoding related options to their default values. Input and output files are retained.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL

on2sc Flix2_SetExportAudio ( FLIX2HANDLE  flix,
const on2bool  bExportAudio 
)

Enable/disable audio output in the current encoding session.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] bExportAudio Enable/Disable
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Note:
Default: on2true

on2sc Flix2_SetExportVideo ( FLIX2HANDLE  flix,
const on2bool  bExportVideo 
)

Enable/disable video output in the current encoding session.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] bExportVideo Enable/Disable
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Note:
Default: on2true

on2sc Flix2_SetExportVideoType ( FLIX2HANDLE  flix,
const FE2_ExportedVideoType  exportVideoType 
)

Set the output file type.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] exportVideoType File type to output
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NOT_SUPP if the video type is unsupported by the engine
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
exportVideoType is a valid member of FE2_ExportedVideoType
Attention:
ExportSWFVectorVideo is unsupported by this version of the engine
Note:
Default: ExportFLVVideo
When using ExportSWF7PlusVideo the video codec should be set to CODEC_H263 with video_options_SetVideoCodec()
Deprecated:
Use the Muxer Interface. This function will be removed in a future release. See also: Muxers.

on2sc Flix2_SetInputFile ( FLIX2HANDLE  flix,
const on2tc inputFile 
)

Set the source file for the encode session.

Attempts to open the input file, extracting the available source information, e.g. video width/height, duration. Addtionally configures the encoder to match the source attributes by calling video_options_Reset() and audio_options_Reset(). For this reason this function should be called before setting any encoder options.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] inputFile Path to the source file.
Return values:
ON2_OK the engine successfully opened the input file for decoding
ON2_INVALID_PARAMS a parameter is invalid.
ON2_NET_ERROR the underlying communication layer failed
<ON2_OK An error occurred opening the file. Call Flix2_Errno() for more detail.
Precondition:
flix is not NULL
inputFile is not NULL
Remarks:
Linux Only: flixd, the encoding server, gets its input from, and writes its output to, the host file system. inputFile must be accessible in this context. An absolute path should be given to help ensure this is the case.

on2sc Flix2_SetOutputFile ( FLIX2HANDLE  flix,
const on2tc outputFile 
)

Set the destination file for the encode session.

When Flix2_Encode() is called an attempt is made to open outputFile.

If the file exists the behavior is determined by the value of Flix2_GetOverwriteExistingFiles():
  • on2true the file will be overwritten
  • on2false a new file will be created of the form: outputFilennn.ext, e.g. out000.flv
Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] outputFile Path to the output file.
Return values:
ON2_OK the engine successfully set the output file
ON2_INVALID_PARAMS should one or more of the preconditions fail
ON2_NO_MEM an error occurred allocating memory for outputFile
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
outputFile is not NULL
Remarks:
Linux Only: flixd, the encoding server, gets its input from, and writes its output to, the host file system. inputFile must be accessible in this context. An absolute path should be given to help ensure this is the case.

on2sc Flix2_SetOverwriteExistingFiles ( FLIX2HANDLE  flix,
const on2bool  bOverwriteExistingFiles 
)

Enable/disable overwriting of existing output files.

The engine's behavior based on this setting is described by Flix2_SetOutputFile()

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] bOverwriteExistingFiles Enable/Disable
Return values:
ON2_OK on success
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Note:
Default: on2false

on2sc Flix2_StopEncoding ( FLIX2HANDLE  flix  ) 

Cancel a running encoding session.

Stops an encoding session started by Flix2_Encode(). The output file will be removed.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
Return values:
ON2_OK the engine successfully stopped the encode
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL

on2sc Flix2_Validate ( const FLIX2HANDLE  flix  ) 

Validate the current encoder settings.

Ensures that the current options set in the engine will allow for an encoding session to be started.

The validation steps performed are:
Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
Return values:
ON2_OK on success
ON2_ERROR on failure
ON2_INVALID_PARAMS should the precondition fail
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL

const char* Flix2_Version (  ) 

Returns the library version as a string.


On2 Technologies, Inc Flix Engine Linux documentation, generated on Tue Nov 2 16:53:01 2010 by doxygen 1.5.5