LibMuse 6.0.2
com.choosemuse.libmuse.MuseFileWriter Class Referenceabstract

Public Member Functions

abstract boolean open ()
 
abstract boolean close ()
 
abstract void discardBufferedPackets ()
 
abstract boolean flush ()
 
abstract int getBufferredMessagesCount ()
 
abstract int getBufferedMessagesSize ()
 
abstract void addArtifactPacket (int id, MuseArtifactPacket packet)
 
abstract void addDataPacket (int id, MuseDataPacket packet)
 
abstract void addAnnotationString (int id, String annotation)
 
abstract void addAnnotation (int id, AnnotationData annotation)
 
abstract void addConfiguration (int id, MuseConfiguration configuration)
 
abstract void addVersion (int id, MuseVersion version)
 
abstract void addComputingDeviceConfiguration (int id, ComputingDeviceConfiguration configuration)
 
abstract void addDsp (int id, DspData dsp)
 
abstract void setTimestampMode (TimestampMode mode)
 
abstract void setTimestamp (long timestamp)
 

Static Public Member Functions

static native MuseFileWriter getFileWriter (MuseFile file)
 

Detailed Description

This class manages saving Muse packets and other data into a file, which can later be read and replayed by MusePlayer. Google Protobuf is used to store the information. For better control, data is not written to the file immediately, but stored in a buffer instead. The buffer then can be flushed to a file or discarded.

Note that upon creation of a MuseFileWriter , an Annotation and the ComputingDeviceConfiguration are automatically written out to the file. The annotation contains the app's name and version and libmuse version. If app's name and version can not be determined, they will be empty strings. The ComputingDeviceConfiguration contains hardware information for the computing device. If any information fields can not be determined, they will be empty strings.

Threading: It is thread safe, so you can call write()/get()/flush()/discard() operations from different threads.

Warning
If you don't call flush() method, messages will be accumulated in memory and eventually you will get memory overflow error. It's library client responsibility to call flush() or discardBufferedPackets() and to clean the memory. You can use helper methods to get how many messages are currently stored in the buffer and how much memory is used.
See also
MusePlayer: http://developer.choosemuse.com/research-tools/museplayer

Member Function Documentation

§ addAnnotation()

abstract void com.choosemuse.libmuse.MuseFileWriter.addAnnotation ( int  id,
AnnotationData  annotation 
)
abstract

Adds annotation data structure to the buffer. Similar to addAnnotationString(), but this method allows you to extra fields. Empty fields in annotation struct won't be added to protobuf. If annotation.data field is empty, method returns immediately.

Parameters
idThe id of the device generating the annotation. This is arbitrary and is used to differentiate data from multiple devices in a single file.
annotationThe annotation data to add.

§ addAnnotationString()

abstract void com.choosemuse.libmuse.MuseFileWriter.addAnnotationString ( int  id,
String  annotation 
)
abstract

Adds an annotation string to the buffer. It may be useful if you want to log specific events. This is a simplified version of addAnnotation(). Use this method if you want to add one string to protobuf. Use addAnnotation() for more advanced options. This function does nothing if annotation is empty.

Parameters
idThe id of the device generating the packet. This is arbitrary and is used to differentiate data from multiple devices in a single file.
annotationThe annotation string to add.

§ addArtifactPacket()

abstract void com.choosemuse.libmuse.MuseFileWriter.addArtifactPacket ( int  id,
MuseArtifactPacket  packet 
)
abstract

Adds MuseArtifactPacket to the buffer.

Parameters
idThe id of the device generating the packet. This is arbitrary and is used to differentiate data from multiple devices in a single file.
packetThe artifact packet to add.

§ addComputingDeviceConfiguration()

abstract void com.choosemuse.libmuse.MuseFileWriter.addComputingDeviceConfiguration ( int  id,
ComputingDeviceConfiguration  configuration 
)
abstract

Adds information about the running device to the buffer.

Parameters
idThe id of the device saving the configuration. This is arbitrary and is used to differentiate data from multiple devices in a single file.
configurationThe device configuration data to add.

§ addConfiguration()

abstract void com.choosemuse.libmuse.MuseFileWriter.addConfiguration ( int  id,
MuseConfiguration  configuration 
)
abstract

Adds MuseConfiguration to the buffer.

Parameters
idThe id of the device saving the configuration. This is arbitrary and is used to differentiate data from multiple devices in a single file.
configurationThe configuration data to add.

§ addDataPacket()

abstract void com.choosemuse.libmuse.MuseFileWriter.addDataPacket ( int  id,
MuseDataPacket  packet 
)
abstract

Adds MuseDataPacket to the buffer. All current packets are supported.

Parameters
idThe id of the device generating the packet. This is arbitrary and is used to differentiate data from multiple devices in a single file.
packetThe data packet to add.

§ addDsp()

abstract void com.choosemuse.libmuse.MuseFileWriter.addDsp ( int  id,
DspData  dsp 
)
abstract

With this method you can save your custom data. Checkout protobuf schema for details: http://developer.choosemuse.com/file-formats/muse

Parameters
idThe id of the device saving the data. This is arbitrary and is used to differentiate data from multiple devices in a single file.
dspThe data to store.

§ addVersion()

abstract void com.choosemuse.libmuse.MuseFileWriter.addVersion ( int  id,
MuseVersion  version 
)
abstract

Adds MuseVersion to the buffer.

Parameters
idThe id of the device saving the version. This is arbitrary and is used to differentiate data from multiple devices in a single file.
versionThe version data to add.

§ close()

abstract boolean com.choosemuse.libmuse.MuseFileWriter.close ( )
abstract

Closes the file. Calls MuseFile.close() You don't have to call close explicitly unless you want to close file immediately. close is called automatically, when the file writer object is destroyed.

Returns
false if the file could not be closed for any reason. true otherwise.

§ discardBufferedPackets()

abstract void com.choosemuse.libmuse.MuseFileWriter.discardBufferedPackets ( )
abstract

Removes all saved messages from the memory.

§ flush()

abstract boolean com.choosemuse.libmuse.MuseFileWriter.flush ( )
abstract

Flashes saved messages to the disk. Calls MuseFile.write()

Returns
false if can not write to file for any reason. true otherwise.

§ getBufferedMessagesSize()

abstract int com.choosemuse.libmuse.MuseFileWriter.getBufferedMessagesSize ( )
abstract

Returns the size of saved messages in bytes.

Returns
the size of the saved messages in bytes.

§ getBufferredMessagesCount()

abstract int com.choosemuse.libmuse.MuseFileWriter.getBufferredMessagesCount ( )
abstract

Returns number of saved messages

Returns
the number of saved messages.

§ getFileWriter()

static native MuseFileWriter com.choosemuse.libmuse.MuseFileWriter.getFileWriter ( MuseFile  file)
static

Returns an instance of file writer. Automatically opens a file.

Returns
an instance of the file writer.

§ open()

abstract boolean com.choosemuse.libmuse.MuseFileWriter.open ( )
abstract

Opens a file if it exists or creates a new one. If file already exists, all new messages will be appended at the end. Use this method if you explicitly closed file and want to open it again. Calls MuseFile.open()

Returns
false if the file could not be opened for any reason. true otherwise.

§ setTimestamp()

abstract void com.choosemuse.libmuse.MuseFileWriter.setTimestamp ( long  timestamp)
abstract

Set the timestamp for the next message to be written.

This only does anything in explicit timestamp mode. In explicit mode, the timestamp set by set_timestamp applies to the next message and all subsequent messages. If set_timestamp is not called, then the timestamp is 0.

In all other modes, calling set_timestamp causes an assert failure – the app crashes in debug mode, and it is a noop in release mode.

The timestamp is in microseconds since some epoch (usually Jan 1, 1970).

Parameters
timestampThe time to use for the timestamp in microseconds.

§ setTimestampMode()

abstract void com.choosemuse.libmuse.MuseFileWriter.setTimestampMode ( TimestampMode  mode)
abstract

Set the timestamp mode.

By default, the mode is TimestampMode.LEGACY

Parameters
modeThe timestamp mode to set.

The documentation for this class was generated from the following file: