This document will describe the functionality and purpose of the UniversalMixMachine web service, provided by Moodmixer GmbH.
The UniversalMixMachine web service provides users with an online tool that delivers a calculated and in length defined list based on almost arbitrary data and a history of previously delivered items. Typical use cases are musical play lists, dynamic product presentations or recommendations for web visitors. Since the UniversalMixMachine calculates the returned list by a complete analysis of base data and logs the result will always be different from previous lists and absolutely up to date at the same time. The process can be fully automated, what makes it possible to deliver user related content dynamically without any further interaction.
The selection of items is conducted on the basis of threee possible algorithms. These can be combined and put into a weighed order. Each algorithm can be used for different metadata.
Ranking: The principle of all Moodmixer™-Systems is a rating system. The higher a track is being rated, the “relatively“( in relation to the title pool used) more often it will be used in a playlist.
Ranking columns can also be used for temporary archiving of tracks (value 0 equals “not in use” if activated). Ranking can be used on any kind of data that can be converted into a ranking, such as product age, price, editorial oder user-rating, click rates, sales charts, results from filters or semantic analysis, resuilts from collaborative filtering and many more.
Group distribution (optional): The group algorithm will take care of a homogeneous distribution of values that occur more often in a data library- i.e. if you have an artist in the library that owns many more songs than others you might want to distribute all of his titles evenly across the playlist- without a bulk of songs at one point- then you set “Group” to the Artist column. This is also a good way to control the distribution of i.e. voice type or of product groups and their homogenious distribution. Group algorithms are “non-destructive”- if a title pool doesn’t allow for this distribution it will carefully soften the rule.
Smoothing (optional): This control can be set for values such as BPM, Tempo/ felt tempo, Rhythm-description etc. it aims to prevent too large differences in value change from one item to the next. If the title pool allows it then changes will be made in waves, slowly increasing and decreasing. This control is also non-destructive.
Overview:
UniversalMixMachine web service has one core function called UMMRun
The used parameters:
You need at least a PrimaryID for each planned item.
With this PrimaryID the user should be able to get additional information from his own database if necessary. The second entry will contain the calculated start time of the item, it will only be present if ScheduledStartTime is valid. The third entry will contain the URL of the calculated item if the column type is present. The length of the returned array depends of either the value in ItemsReturn or the amount of items used to fill the time given by ScheduleStartTime and ScheduleEndTime.
In any case the last two entries of the returned array will contain first the parameters passed to the function except MixData and LogData for control purposes and second a string that will be “No Errors!”, if everything worked fine. So, if an error occurred and the function was able to return the object array, it will be just two entries long. One can say for a rule that, if the returned array length is lower or equal two, something went wrong.
The parameters:
All UMMRun function parameters are of type string to avoid any type mismatch. But there are some crucial aspects that should have special attention:
All four parameters ColTypes, ActiveColumns, ColumnRestrictions and ColRanks must exactly reflect the amount of columns in . I.e. if has 4 columns ColTypes must also contain 4 numbers separated by a ‘;’: “0;2;9;11″
MixData, LogData must be separated by the same ColumnSeparator and RowSeparator and these separators should be safe, means, neither MixData nor LogData entries should contain them.
| Key |
Status: mandatoryType: String
Purpose: authenticates the web service call
You can purchase a valid key from Moodmixer GmbH. The web service will only work with a valid key!
|
| ColumnSeparator |
Status: mandatoryType: String
Purpose: Mix-Data
You can use any printable character but it’s not recommended, because there is the risk, that MixData already contains those characters. Better use TAB or RETURN instead.
ColumnSeparator must be different from RowSeparator!
|
| RowSeparator |
Status: mandatoryType: StringPurpose: the character or string to separate each row of Mix-Data
You can use any printable character but it’s not recommended, because there is always the risk, that MixData already contains those characters. Better use TAB or RETURN instead.
RowSeparator must be different from ColumnSeparator!
|
| MixData |
Status: mandatoryType: StringPurpose: the planning data as plain text, fields are seperated by ColumnSeparator, rows by RowSeparator
|
| ColTypes |
Status: mandatoryType: String consisting of integer numbers separated by a semicolon (;)
Purpose: Defines the function of each column/field in MixData to be interpreted by the UniversalMixMachine
There are currently 10 different types of columns. The PrimaryID column must always be present, it will be returned by the UniversalMixMachine to identify the data item. One of the three column types Ranking, Group or Smoothing must also be present and active. All other column types are optional but DurationInSeconds should be present, if exact timing is important, otherwise the <%UMM%> will assume a default duration value.
- PrimaryID=0 (mandatory)
- Ranking=1 (values in this column will be interpreted as preferences: higher values means relatively more ‘plays’)
- Group=2 (values in this column will be grouped if identical and distributed according to their amount)
- Smoothing=4 (values in this column will be interpreted as ’steps’ to avoid great ‘jumps’ from item to item)
- LinkedItem=6
- CueIn=7 (values in this column will be interpreted as play mark relative to start of song in seconds and will be subtracted from DurationInSeconds)
- CueOut=8 (values in this column will be interpreted as end play mark relative to end of song in seconds and will be subtracted from DurationInSeconds)
- DurationInSeconds=9 (values in this column will be interpreted as total duration of item in seconds including existing cues)
- URL=10 (values in this column will be interpreted as path to physical media)
- Jingle=11 (values in this column will be interpreted as indicator that the item is a jingle and rotation restrictions will not be applied, values are 0=no jingle or <>0=jingle)
Example: 0;1;9
says that there are three columns in MixData. First is of type PrimaryID, second of type Ranking and third of type DurationInSeconds |
| ItemsReturn |
Status: optional
Type: String
Purpose: Sets the length of play list to return
if this value is NULL or 0 and ScheduleStartTime and ScheduleEndTime are not valid the UniversalMixMachine will return an empty playlist.
This value should not be bigger than 1000, especially when MixData are large, because the risk of timeout increases.
|
| ActiveColumns |
Status: mandatory
Type: String consisting of ‘0′ or ‘1′ separated by a semicolon (;)
Purpose: Defines the activity status of each column/field in MixData to be interpreted by the UniversalMixMachine
Active columns must be of type Ranking, Group or Smoothing. There must be at least one active column, otherwise the UniversalMixMachine will return an empty play list. PrimaryID columns are automatically active and so must not be set.
Example: 0;1;0 (column types: 0;1;9)
says that there are three columns in MixData. Only the second column is active (and of type Ranking).
|
| ColumnRestrictions |
Status: mandatory
Type: String consisting of ‘0′ or ‘1′ separated by a semicolon (;)
Purpose: Defines the restriction status of each column/field in MixData to be interpreted by the UniversalMixMachine
If a column has restriction enabled, the UniversalMixMachine will try to avoid an immediate repetition of an item with the identical value in the column field.
1;0;0 (column types
says that there are three columns in MixData. Only the first column is restricted (and of type PrimaryID).
|
| SmoothingValues |
Status: obsolet
Should be NULL or empty string.
|
| ColRanks |
Status: mandatory
Type: String consisting of integer numbers separated by a semicolon (;)
Purpose: Defines the priority of columns in MixData to be calculated by the UniversalMixMachine
Lower values mean higher priority, negative values are not valid. Will only be evaluated for active columns except PrimaryID
Example: 20;10;50 (column types: 0;1;9, active: 0;1;0)
says that there are three columns in MixDataRanking), so only the value 10 will be evaluated.
|
| LogData |
Status: optionalPurpose: play history data as plain text consisting of two values for each row, PrimaryID and play date, fields are seperated by ColumnSeparator, rows by RowSeparator
Sequence of the two values doesn’t matter but must be the same throughout the whole list. One must be a valid date the other one must NOT be a date.
The UniversalMixMachine will calculate the play list based on log data if present. Otherwise it will give every item of MixData a virtual random play date.
Example: ID1234 20081205T223417
ID0765 20081205T223705
ID8888 20081205T224123
IDxyz 20081205T224500
the date field can have any valid date format i.e. 11/30/08 7:14
|
| LogScope |
Status: obsolet
Should be NULL or empty string.
|
| LogStart |
Status: obsolet
Should be NULL or empty string.
|
| PriorDay |
Status: optionalType: String ‘0′ or ‘1′
Purpose: if set to any value different from ‘0′ the UniversalMixMachine will try to avoid planning of songs that has been played the day before inside the PriorDayScope |
| PriorDayScope |
Status: optionalType: Integer number as string
Purpose: if set to any value different from ‘0′ and the flag is set the UniversalMixMachine will try to avoid planning of songs that has been played the day before inside a scope of given minutes x2.
Example: If the current planning time is 6:15 p.m. and the given PriorDayScope is 15 minutes, the UniversalMixMachine will not play songs that have been played the day before between 6:00 p.m. and 6:30 p.m. As long as there are no playable UniversalMixMachine will automatically narrow the scope until playable songs are found. |
| PWRA |
Status: optionalType: String of value ‘0′ or ‘1′
Purpose: if set to any value different from ‘0′ the UniversalMixMachine MixData. |
| ScheduleStartTime |
Status: optionalType: Date value as String
Purpose: if set to any value different from NULL or empty string and ScheduleEndTime is a valid date value later than ScheduleStartTime the UniversalMixMachine will plan items either by DurationInSeconds or a fixed default value of 3 Minutes until the ScheduleEndTime is reached. |
| ScheduleEndTime |
Status: optionalType: Date value as String
Purpose: if set to any value different from NULL or empty string and ScheduleStartTime is a valid date value earlier than ScheduleEndTime the UniversalMixMachine will plan items either by DurationInSeconds or a fixed default value of 3 Minutes until the ScheduleEndTime is reached. |
|
|
News
