Player
C Reference » Production Nodes Functionality

## Functions

XN_C_API XnStatus XN_C_DECL | xnCreatePlayer (XnContext *pContext, const XnChar *strFormatName, XnNodeHandle *phPlayer)
XN_C_API XnStatus XN_C_DECL | xnSetPlayerRepeat (XnNodeHandle hPlayer, XnBool bRepeat)
XN_C_API XnStatus XN_C_DECL | xnSetPlayerSource (XnNodeHandle hPlayer, XnRecordMedium sourceType, const XnChar *strSource)
XN_C_API XnStatus XN_C_DECL | xnGetPlayerSource (XnNodeHandle hPlayer, XnRecordMedium *pSourceType, XnChar *strSource, XnUInt32 nBufSize)
XN_C_API XnStatus XN_C_DECL | xnPlayerReadNext (XnNodeHandle hPlayer)
XN_C_API XnStatus XN_C_DECL | xnSeekPlayerToTimeStamp (XnNodeHandle hPlayer, XnInt64 nTimeOffset, XnPlayerSeekOrigin origin)
XN_C_API XnStatus XN_C_DECL | xnSeekPlayerToFrame (XnNodeHandle hPlayer, const XnChar *strNodeName, XnInt32 nFrameOffset, XnPlayerSeekOrigin origin)
XN_C_API XnStatus XN_C_DECL | xnTellPlayerTimestamp (XnNodeHandle hPlayer, XnUInt64 *pnTimestamp)
XN_C_API XnStatus XN_C_DECL | xnTellPlayerFrame (XnNodeHandle hPlayer, const XnChar *strNodeName, XnUInt32 *pnFrame)
XN_C_API XnStatus XN_C_DECL | xnGetPlayerNumFrames (XnNodeHandle hPlayer, const XnChar *strNodeName, XnUInt32 *pnFrames)
XN_C_API const XnChar *XN_C_DECL | xnGetPlayerSupportedFormat (XnNodeHandle hPlayer)
XN_C_API XnStatus XN_C_DECL | xnEnumeratePlayerNodes (XnNodeHandle hPlayer, XnNodeInfoList **ppList)
XN_C_API XnBool XN_C_DECL | xnIsPlayerAtEOF (XnNodeHandle hPlayer)
XN_C_API XnStatus XN_C_DECL | xnRegisterToEndOfFileReached (XnNodeHandle hPlayer, XnStateChangedHandler handler, void *pCookie, XnCallbackHandle *phCallback)
XN_C_API void XN_C_DECL | xnUnregisterFromEndOfFileReached (XnNodeHandle hInstance, XnCallbackHandle hCallback)
XN_C_API XnStatus XN_C_DECL | xnSetPlaybackSpeed (XnNodeHandle hInstance, XnDouble dSpeed)
XN_C_API XnDouble XN_C_DECL | xnGetPlaybackSpeed (XnNodeHandle hInstance)

## Detailed Description

A Player node is a Production Node that allows playing of a recording. It supports all Production Node functions, and adds additional functions.

## Function Documentation

## xnCreatePlayer()

XN_C_API XnStatus XN_C_DECL xnCreatePlayer | ( | XnContext * | pContext,
|  | const XnChar * | strFormatName,
|  | XnNodeHandle * | phPlayer )

Creates a player.

Parameters

  pContext | [in] The context in which to create the player.
  strFormatName | [in] The name of the recording format that the created player should play.
  phPlayer | [out] Pointer to the created player handle.

## xnEnumeratePlayerNodes()

XN_C_API XnStatus XN_C_DECL xnEnumeratePlayerNodes | ( | XnNodeHandle | hPlayer,
|  | XnNodeInfoList ** | ppList )

Retrieves a list of the nodes played by a player.

Parameters

  hPlayer | [in] A handle to the player.
  ppList | [out] A pointer to the retrieved list of nodes.

Remarks
  This function fills the pointer that is pointed to by ppList with a newly allocated node info list of the played nodes. This list must later be freed by the caller with xnNodeInfoListFree().

## xnGetPlaybackSpeed()

XN_C_API XnDouble XN_C_DECL xnGetPlaybackSpeed | ( | XnNodeHandle | hInstance | ) |

Gets the playback speed. see xnSetPlaybackSpeed() for more details.

Parameters

  hInstance | [in] A handle to the player.

Returns
  speed ratio, or -1.0 if this node is not a player.

## xnGetPlayerNumFrames()

XN_C_API XnStatus XN_C_DECL xnGetPlayerNumFrames | ( | XnNodeHandle | hPlayer,
|  | const XnChar * | strNodeName,
|  | XnUInt32 * | pnFrames )

Retrieves the number of frames of a specific node played by a player.

Parameters

  hPlayer | [in] A handle to the player.
  strNodeName | [in] The name of the node for which to retrieve the number of frames.
  pnFrames | [out] A pointer to the retrieved number of frames.

## xnGetPlayerSource()

XN_C_API XnStatus XN_C_DECL xnGetPlayerSource | ( | XnNodeHandle | hPlayer,
|  | XnRecordMedium * | pSourceType,
|  | XnChar * | strSource,
|  | XnUInt32 | nBufSize )

Gets the player's source, i.e where the played events come from.

Parameters

  hPlayer | [in] A handle to the player.
  pSourceType | [out] The player's source type.
  strSource | [in] The player's source.
  nBufSize | [in] The size of the buffer specified by strSource.

See also
  xnSetPlayerSource()

## xnGetPlayerSupportedFormat()

XN_C_API const XnChar *XN_C_DECL xnGetPlayerSupportedFormat | ( | XnNodeHandle | hPlayer | ) |

Gets the name of the format supported by a player.

Parameters

  hPlayer | [in] A handle to the player.

Returns
  The name of the format supported by the player, or NULL if hPlayer is NULL.

## xnIsPlayerAtEOF()

XN_C_API XnBool XN_C_DECL xnIsPlayerAtEOF | ( | XnNodeHandle | hPlayer | ) |

Checks whether the player is at the end-of-file marker.

Note
  In the built-in ONI player, this function will never return TRUE for a player that is in repeat mode, although the event registered with xnRegisterToEndOfFileReached() will be fired.

Parameters

  hPlayer | [in] A handle to the player.

See also
  xnSetPlayerRepeat()

## xnPlayerReadNext()

XN_C_API XnStatus XN_C_DECL xnPlayerReadNext | ( | XnNodeHandle | hPlayer | ) |

Reads the next data element from the player.

Can cause data updates and/or property updates of the played nodes.

Parameters

  hPlayer | [in] A handle to the player.

## xnRegisterToEndOfFileReached()

XN_C_API XnStatus XN_C_DECL xnRegisterToEndOfFileReached | ( | XnNodeHandle | hPlayer,
|  | XnStateChangedHandler | handler,
|  | void * | pCookie,
|  | XnCallbackHandle * | phCallback )

Registers a callback function to be called when end-of-file is reached.

Parameters

  hPlayer | [in] A handle to the player.
  handler | [in] A pointer to a function that will be called.
  pCookie | [in] A user cookie that will be passed to the callback function.
  phCallback | [out] Will be filled with a handle to be passed to xnUnregisterFromEndOfFileReached().

See also
  xnSetPlayerRepeat()

## xnSeekPlayerToFrame()

XN_C_API XnStatus XN_C_DECL xnSeekPlayerToFrame | ( | XnNodeHandle | hPlayer,
|  | const XnChar * | strNodeName,
|  | XnInt32 | nFrameOffset,
|  | XnPlayerSeekOrigin | origin )

Seeks the player to a specific frame of a specific played node, so that playing will continue from that frame onwards.

Parameters

  hPlayer | [in] A handle to the player.
  strNodeName | [in] The name of the node whose frame is to be sought.
  nFrameOffset | [in] The number of frames to move, relative to the specified origin. See the remark below.
  origin | [in] The origin to seek from. See the remark below.

Remarks
  The meaning of the nTimeOffset parameter changes according to the origin parameter:

origin | Meaning of the nFrameOffset parameter
XN_PLAYER_SEEK_SET | nFrameOffset specifies the total number of frames since the beginning of the node's recording. Note that nFrameOffset will be case to XnUInt64 in this case.
XN_PLAYER_SEEK_CUR | nFrameOffset specifies the number of frames to move, relative to the current frame of the specifies node. A positive value means move forward, and a negative value means move backwards.
XN_PLAYER_SEEK_END | nFrameOffset specifies the number of frames to move, relative to the end of the node's recording. This must be a negative value.

Note
  You can get different results using this function for different values of strNodeName, because the frame numbers of different nodes are not necessarily in sync.

## xnSeekPlayerToTimeStamp()

XN_C_API XnStatus XN_C_DECL xnSeekPlayerToTimeStamp | ( | XnNodeHandle | hPlayer,
|  | XnInt64 | nTimeOffset,
|  | XnPlayerSeekOrigin | origin )

Seeks the player to a specific timestamp, so that playing will continue from that point onwards.

Note
  For the built-in ONI player, this function is not currently supported and always returns XN_STATUS_NOT_IMPLEMENTED.

Parameters

  hPlayer | [in] A handle to the player.
  nTimeOffset | [in] The offset, in microseconds, to move, relative to the specified origin. See the remark below.
  origin | [in] The origin to seek from. See the remark below.

Remarks
  The meaning of the nTimeOffset parameter changes according to the origin parameter:

origin | Meaning of the nTimeOffset parameter
XN_PLAYER_SEEK_SET | nTimeOffset specifies the total time passed since the beginning of the recording. Note that nTimeOffset will be case to XnUInt64 in this case.
XN_PLAYER_SEEK_CUR | nTimeOffset specifies a period of time to move, relative to the current player position. A positive value means move forward, and a negative value means move backwards.
XN_PLAYER_SEEK_END | nTimeOffset specifies a period of time to move, relative to the end of the recording. This must be a negative value.

## xnSetPlaybackSpeed()

XN_C_API XnStatus XN_C_DECL xnSetPlaybackSpeed | ( | XnNodeHandle | hInstance,
|  | XnDouble | dSpeed )

Sets the playback speed, as a ratio of the time passed in the recording. A value of 1.0 means the player will try to output frames in the rate they were recorded (according to their timestamps). A value bigger than 1.0 means fast-forward, and a value between 0.0 and 1.0 means slow-motion. The special value of XN_PLAYBACK_SPEED_FASTEST (0.0) means there will be no delay, and that frames will be returned as soon as asked for.

Parameters

  hInstance | [in] A handle to the player.
  dSpeed | [in] The speed ratio (see function description).

## xnSetPlayerRepeat()

XN_C_API XnStatus XN_C_DECL xnSetPlayerRepeat | ( | XnNodeHandle | hPlayer,
|  | XnBool | bRepeat )

Determines whether the player will automatically rewind to the beginning of the recording when reaching the end.

Parameters

  hPlayer | [in] A handle to the player.
  bRepeat | [in] Determines whether the player will repeat or not.

Remarks
  If bRepeat is set to TRUE, the player will automatically rewind when reaching the end.
  If bRepeat is set to FALSE, the player will stop playing when reaching the end, and will raise the event that was registered with xnRegisterToEndOfFileReached(). In this state, xnIsPlayerAtEOF() returns TRUE.

## xnSetPlayerSource()

XN_C_API XnStatus XN_C_DECL xnSetPlayerSource | ( | XnNodeHandle | hPlayer,
|  | XnRecordMedium | sourceType,
|  | const XnChar * | strSource )

Sets the source for the player, i.e. where the played events will come from.

The only supported source type at this point is a file.

Parameters

  hPlayer | [in] A handle to the player.
  sourceType | [in] The type of source to set. Currently only XN_RECORD_MEDIUM_FILE is supported.
  strSource | [in] The source from which to play. If sourceType is XN_RECORD_MEDIUM_FILE, strSource specifies a file name.

See also
  xnGetPlayerSource()

## xnTellPlayerFrame()

XN_C_API XnStatus XN_C_DECL xnTellPlayerFrame | ( | XnNodeHandle | hPlayer,
|  | const XnChar * | strNodeName,
|  | XnUInt32 * | pnFrame )

Reports the current frame number of a specific node played by a player.

Parameters

  hPlayer | [in] A handle to the player.
  strNodeName | [in] The name of the node for which to report the frame number.
  pnFrame | [out] A pointer to the reported frame number.

Remarks
  Different nodes that belong to the player can have different frame numbers, because the nodes are not necessarily in sync.

## xnTellPlayerTimestamp()

XN_C_API XnStatus XN_C_DECL xnTellPlayerTimestamp | ( | XnNodeHandle | hPlayer,
|  | XnUInt64 * | pnTimestamp )

Reports the current timestamp of a player, i.e. the amount of time passed since the beginning of the recording.

Parameters

  hPlayer | [in] A handle to the player.
  pnTimestamp | [out] A pointer to the retrieved timestamp in microseconds.

## xnUnregisterFromEndOfFileReached()

XN_C_API void XN_C_DECL xnUnregisterFromEndOfFileReached | ( | XnNodeHandle | hInstance,
|  | XnCallbackHandle | hCallback )

Unregisters a callback function which was registered using xnRegisterToEndOfFileReached().

Parameters

  hInstance | [in] A handle to the player.
  hCallback | [in] The handle to the callback returned from xnRegisterToEndOfFileReached().