Edit

ISpatialAudioMetadataWriter::WriteNextItem method (spatialaudiometadata.h)

  • Article

Starts a new metadata item at the specified offset.

Syntax

HRESULT WriteNextItem(
  [in] UINT16 frameOffset
);

Parameters

[in] frameOffset

The frame offset of the item within the range specified with the frameCount parameter to ActivateSpatialAudioMetadataItems.

Return value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return code Description
SPTLAUD_MD_CLNT_E_NO_ITEMS_OPEN
 The ISpatialAudioMetadataItems has not been opened for writing with a call to Open or the object has been closed for writing with a call to Close.
SPTLAUD_MD_CLNT_E_FRAMEOFFSET_OUT_OF_RANGE
 The number of items written in the writing session is greater than the value supplied in the MaxMetadataItemCount field in the SpatialAudioObjectRenderStreamForMetadataActivationParam passed into ISpatialAudioClient::ActivateSpatialAudioStream.

The frameCount value is greater than the value of the frameCount parameter to ActivateSpatialAudioMetadataItems and the overflow mode was set to SpatialAudioMetadataWriterOverflow_Fail.
E_INVALIDARG
 The value of frameOffset is not greater than the value provided in the previous call to WriteNextItem within the same writing session.

Remarks

Before calling WriteNextItem, you must open the ISpatialAudioMetadataWriter for writing by calling Open after the object is created and after Close has been called. During a writing session demarcated by calls to Open and Close, the value of the frameOffset parameter must be greater than the value in the preceding call.

Within a single writing session, you must not use WriteNextItem to write more items than the value supplied in the MaxMetadataItemCount field in the SpatialAudioObjectRenderStreamForMetadataActivationParam passed into ISpatialAudioClient::ActivateSpatialAudioStream or an SPTLAUD_MD_CLNT_E_FRAMEOFFSET_OUT_OF_RANGE error will occur.

If the overflow mode is set to SpatialAudioMetadataWriterOverflow_Fail, the value of the frameOffset parameter must be less than he value of the frameCount parameter to ActivateSpatialAudioMetadataItems or an SPTLAUD_MD_CLNT_E_FRAMEOFFSET_OUT_OF_RANGE error will occur.

After calling WriteNextItem, call WriteNextItemCommand to write metadata commands and value data for the item.

Requirements

Requirement Value
Target Platform Windows
Header spatialaudiometadata.h

See also

ISpatialAudioMetadataWriter