Samplitude integration task¶

• Table of contents
• Samplitude integration task
  • End-user task list
  • Functional description
  • Sound file
  • Metadata
  • Metadata description
  • Metadata exchange logic
    • New item
    • Saving back
    • Samplitude Private data

End-user task list¶

1. "Open from Digispot".
   This action called from Samplitude environment (ex: by toolbar button) and allows user to select item from Digispot database (in native Digispot GUI) and open it’s sound file editing in Samplitude. All item’s metadata can also be retrieved.
2. "Save [as] to Digispot".
   This action called from Samplitude environment and allows user to select item from Digispot database (in native Digispot GUI) and save edited sound in this item. Item’s metadata can be passed in this method.
3. "Open in Samplitude".
   This action called from Digispot environment and allows user to open selected item for editing in Samplitude. Result is same as "Open from Digispot" but initiated from Digispot.

Functional description¶

1. All requests are served by special process, running on the same workplace - Digispot server application (DSA)
2. There is a special library to integrate in Samplitude. Library should be build as WIN32 dll.
3. This library communicate with DSA by internal protocol
4. Library can start DSA, if necessary
5. Library, in general, has three main features
   1. Method to ask user to select item from Digispot database for opening and return it’s metadata
   2. Method to ask user to select item from Digispot database for saving (after edit or add new) and apply passed metadata
   3. Way to make incoming call to Samplitude API when "Open in Samplitude" task initiated in DSA
      1. To allow to do it in any time, library must be loaded to Samplitude all the time that it works.
6. All metadata, including sound file name, database id and all item description are passed as XML string in both direction.
7. We need to know Digispot user to determine it’s privileges. In case of Windows authorization we get it automatically, but in case of usual Digispiot login we need to ask user’s login and password before "Open from Digispot" and "Save to Digispot" operations. Of course, library can remember user’s data during one session and ask it only once.

Sound file¶

There are following nuances:

• There are Digispot file formats that are private and not supported by Samplitude
• Part of Digispot sound editing are parameters that stored as metadata in private format
• Digispot manipulate files in internal file storage by it’s internal logic

Depending on these points we need to create universal file exchange method. We suggest the following:

* Digispot -> Samplitude

* When sound should be passed to Samplitude, it will be mixed down (by DSA) as standard sound file to specified folder (outside of Digispot storage) in standard format and compression - for example, *.wav with PCM. All Digispot editing would be applied to sound file content.

* As we add files to this folder, we need to delete files too. File should be kept as long as it’s enough for user to finish it’s work. We can’t determine this time, so we suggest to keep this files for a week. And delete older files automatically.
Or Samplitude will copy file to its internal storage? In this case Samplitude can delete this file after end of operation.

* Samplitude -> Digispot II

* Same situation. Samplitude should mix down file to special place and pass link to it to Digispot.
File can be deleted after end of operation, because Digispot always copy file to it’s internal storage.

Metadata¶

* Metadata are passed in both ways as XML string.

* String passed to/from Library as UTF-16, Little-endian. (for Windows C it’s BSTR)

* All metadata are stored in XML (or we will pass file name separately of XML)

* Example of metadata file is attached [raw-example.xml here].

* Empty values should not be stored, except of special cases.

* Every tag has attribute dt, that describes type of of tag content. It can be one of the following values:

* i4 - 4 bytes integer

* i8 - 8 bytes integer

* f - float

* b - binary

* s - string. It’s always omitted, except case of a empty string. Empty strings should be just excluded from XML except of special case.

Metadata description¶

* FONO_INFO

* *dbID - *Id in Digispot Database. It’s unique DB item identifier, it never changes

* Type- define one of 5 DB partitions

* 1 - Commercials

* 2 - Jingles

* 3 - Music

* 4 - Broadcasts

* 5 - News

* *!FileName* - item sound file full name

* FONO_STRING_INFO

* Name - Name or title of DB Item

* Artist- Artist[s] of the item. More than one artist can be passed separated by semicolon. Lennon;!McCartney.

* Author - Author[s] of the item. More than one artist can be passed separated by semicolon.

* Category - DB Category[es] to which item belongs. More than one artist can be passed separated by semicolon.

* Album- Album. Single value only.

* Comment - Comment. Can contain multi-line text.

Metadata exchange logic¶

Samplitude will get all metadata of internal item representation. It contains lot of tags, but program should ignore all unknown or unneeded data. May be later part of it became needed.

New item¶

When Samplitude prepare data to create new item in Digispot DB, it must set fileds: Type* and specify file name in !FileName* tag (or we will pass file name separately from XML).  

Additionally, it can fill fields described above. dbID should not be set or should be 0.

Saving back¶

When Samplitude save item back, it must set its dbID, to define which item should be overwritten. And program can also set fields, described above.
If field is not set (not present in XML) - it will keep its value. To erase value, artist, for example, program should pass empty value,

Samplitude Private data¶

There is ability to store any private data in special XML node. Digispot will keep these data and, when item will be opened in Samplitude again, these data will be passed back to Samplitude. I need a time to fine name of this node, I will prepare it later