-
Notifications
You must be signed in to change notification settings - Fork 0
Additional API Doc Comments
The Presentation.RootUri property is an absolute path against which any relative paths specified for that Presentation in the XUK document will be resolved.
If Presentation.RootUri is not set explicitly (i.e. programmatically), the property defaults to the current application folder given by System.IO.Directory.GetCurrentDirectory().
However, when reading a Presentation from XUK (i.e. XukIn() method), a non-existing or empty "rootUri" attribute will result in Presentation.RootUri becoming the URI of the XUK file itself (unless the XML data comes from a memory stream, in which case the default is the current application directory again).
For example, the DataProviders (i.e. audio data sources, actual file locations) for one given Presentation are all managed inside a single folder of which the location is [Presentation.RootUri + DataProviderManager.DataFileDirectory]. Please note that Presentation.RootUri can either be a folder or a file, as the System.Uri class resolves paths transparently in both cases.
The Open/SaveXukActions? are not meant to be used to copy entire project data from one place to another. They are just the underlying mechanism used by the Project.Open/SaveXUK() methods, with support for progress report (ProgressAction, ProgressEvents). They basically take care of de/serializing the XUK data itself, without handling associated media data. The data folder [Presentation.RootUri + DataProviderManager.DataFileDirectory] should be moved manually to the new location. All paths in the data model are resolved dynamically (no hard-coded values), so unless there are open Streams while performing a "save as" operation (an obvious mistake), the model should not become corrupted. Something to keep in mind: the undo-redo stacks may contain active references to managed media data, which will be preserved in XUK which is why it needs to be copied across in the data directory.
TreeNode.Export(Presentation) takes care of cloning fragments of the tree to be used in the specified destination Presentation. It succeeds only if the source and destination Presentation are compatible (same Factories, etc.).
PublishManagedAudioVisitor does more than just copying data, it creates a new type of XUK document with ExternalMedia instead of ManagedMedia. This is therefore useful only at the publishing stage, as it looses important authoring-time information (the active Managed media data of the session). The unit-tests in urakawa.publish.PublishManagedAudioVisitorTests, in particular the PublishTest(Presentation) static function, demonstrate how to generate a single audio file per level-1 (direct TreeNode children of Presentation.RootNode). This can be adapted to meet other needs.
Makes one audio file (i.e. WavClip/FileDataProvider) per MediaData (i.e. per ManagedMedia, but not necessarily per TreeNode).
The copy() method was unnecessarily duplicating FileDataProviders (actual files):
- the copy() method in WavAudioMediaData duplicates ("clones") the WavClips.
- the copy() method in WavClip creates a copy of the DataProvider (this is now removed).
- the copy() method in FileDataProvider delegates the work to the DataProviderManager.
- the AppendDataToProvider() method in DataProviderManager actually copies the bytes across the binary audio streams.
This has been fixed so that step (2) has been removed, so in essence the FileDataProviders are now shared across several WavAudioMediaData. All the operations in WavAudioMediaData (insert, append, merge, etc.) modify the underlying (private) WavClip data structure, in a way that does not create conflicts between shared DataProviders (i.e. physical files). In other words, once a FileDataProvider is created (and potentially shared amongst several WavClips, and therefore amongst different WavAudioMediaData), the file content is never touched. The presentation never becomes corrupted.
The "cleanup" mechanism implemented in FileDataProviderManager::removeUnusedDataProviders(true) actually deletes files, making it impossible to recover the data (i.e. undo is impossible).
The "cleanup" mechanism implemented in Presentation::cleanup() checks the undo/redo stack as well as making one audio file per used MediaData (i.e. WavAudioMediaData.forceSingleDataProvider()):
The Progress feature was introduced to facilitate displaying a progress report (i.e. progress bar UI widget) during lengthy operations within the SDK. It is currently only implemented for the XukIn/Out() methods. This is largely insufficient, as the XML (de)serialization is actually quite fast even for very large XUK files. We need to make that feature available for file copy methods as well (manipulation of binary streams).