Creating a MIDI Application
This tutorial describes the usage of MIDI API of the Hardware API. With the MIDI API an application can interact with MIDI controllers connected to a TV over USB, play standard MIDI files, and use simulated MIDI controllers.
The application being developed in this tutorial demonstrates the development of an application that uses MIDI controller devices. The application accesses a MIDI controller device, plays a MIDI file, and has its own simulated MIDI keyboard.
Programming of applications using MIDI class is based on the MIDI API of the Hardware API.
Development Environment
Use Samsung Smart TV SDK(4.0 and above) to develop the application. The emulator provided along with the SDK can be used to debug and test the application before deploying it onto a TV. Refer Testing Your Application on a TV. Note that applications may perform better on the TV than on the emulator.
You can find general instructions for creating applications in Implementing Your Application Code.
Prerequisites
To develop TV applications, you need:
- a Samsung TV connected to the Internet
- SDK (Samsung Smart TV SDK 4.0 and above is must) or a text editor for creating HTML, JavaScript and CSS files
Source Files
Note
The files needed for the sample application are here.
The tutorial MIDI Application is located under Tutorial_MIDI. Source files in directory are explained in the table:
Directory | Description |
---|---|
CSS | Contains the StyleSheet file mycss.css |
Midi | Contains a test midi file test.mid |
JavaScript |
Contains the JavaScript file main.js which does the following:
|
Resources | Contains the image folder which contains common images |
Starting the MIDI Application
To start the MIDI application,
-
Select Open App on the menu and select MIDI_Tutorial.
The following display on the emulator indicates that the application has been selected:
Figure: Selecting the MIDI Tutorial application.
-
Select MIDI_Tutorial and press OK. If the following display appears on the emulator, it means that the application has started successfully:
Figure: MIDI application started
-
Connect a USB MIDI keyboard to the TV.
Connected MIDI keyboard name is listed on the left side in MIDI Controller Devices list.
Figure: Connected MIDI
Using the MIDI
Following sections explain how to use the connected MIDI controller.
-
If you want to enable and play the connected MIDI keyboard, bring focus to the listed MIDI keyboard and press the Enter key on the remote control.
After pressing the enter key, you can see the configure screen enabled as shown on the figure below.
Figure: Activate the MIDI device
Now pressing any key on the MIDI keyboard will play the corresponding note.
If you want to stop and disable the connected MIDI keyboard, just press the Enter key on the remote control again.
-
Notes can be directly heard by pressing keys on the software simulated keyboard as shown on the figure below.
Figure: Play the MIDI keyboard
-
Standard MIDI file can be played simply by pressing the Play ( ► ) key of the remote control.
Pressing the Stop ( ■ ) key on the remote control will stop the MIDI file playback, as on the figure below.
Figure: Play MIDI file
-
You can set the channel, channel instruments, volume parameter and so on as shown on the figure below.
Below figure shows the display change on screen:
Figure: Set synthesizer parameters
You can navigate across the parameters by pressing left / right key key of the remote control on each item.
Pressing up and down keys will change values of respective parameters.
Getting connected MIDI devices
If MIDI keyboards are connected, the window.webapis.mididevice.getMIDIDevices() function will return each MIDI device instance related to each of the connected MIDI keyboards.
Function | Description |
---|---|
getMIDIDevices | Get MIDI keyboards device instances connected to TV. When it is called for the first time, it will initialize all the internal modules. |
MidiWidget.onLoad = function () {
...
midi.getMIDIDevices(MidiWidget.onCustomObtained);
};
MidiWidget.onCustomObtained = function (midis) {
};
Registering a Callback Function for a Device Connection Event
To receive a device connection event, register a callback function with window.webapis.mididevice.registerManagerCallback(). Once the callback registration is done, callback functions are called on connecting or disconnecting a MIDI controller devices such as MIDI keyboards. The callback function can get window.webapis.mididevice.ManagerEvent class object including event type and MIDI name as an input parameter.
Function | Description |
---|---|
registerManagerCallback | Register callback function to get the event for CONNECT/DISCONNECT. |
var midi = window.webapis.mididevice || {};
MidiWidget.onLoad = function () {
gWidgetAPI = new Common.API.Widget();
gTVKey = new Common.API.TVKeyValue();
gWidgetAPI.sendReadyEvent();
...
midi.registerManagerCallback(MidiWidget.onDeviceStatusChange);
midi.getMIDIDevices(MidiWidget.onCustomObtained);
};
MidiWidget.onCustomObtained = function (midis) {
...
gInitSuccess = true;
};
MidiWidget.onDeviceStatusChange = function (sParam) {
if (sParam.deviceType == midi.MIDI_DEVICE_SYNTHESIZER) {
...
} else {
switch(Number(sParam.eventType)){
case midi.MGR_EVENT_DEV_CONNECT:
...
break;
case midi.MGR_EVENT_DEV_DISCONNECT:
...
break;
defaut:
break;
}
}
}
play or stop playing MIDI
The MIDI module can play the MIDI keyboard or the standard MIDI file by calling the midi.startStream function. To stop playing the MIDI keyboard or the MIDI file, call the midi.stopStream function.
Function | Description |
---|---|
startStream | Acitvate the MIDI keyboard to play notes on key press or begin to play MIDI file. |
stopStream | Deactivate the MIDI keyboard from playing the notes on key press or stop playing the MIDI file. |
var sourceDeviceInfo = new midi.MIDIDeviceInfo();
sourceDeviceInfo.deviceName = o.device.getName();
sourceDeviceInfo.deviceID = o.device.getDeviceID();
sourceDeviceInfo.deviceType = o.device.getType();
var destDeviceInfo = new midi.MIDIDeviceInfo();
destDeviceInfo.deviceName = midisynthInstance.getName();
destDeviceInfo.deviceID = midisynthInstance.getDeviceID();
destDeviceInfo.deviceType = midi.MIDI_DEVICE_SYNTHESIZER;
midi.startStream(sourceDeviceInfo, destDeviceInfo);
var sourceDeviceInfo = new midi.MIDIDeviceInfo();
sourceDeviceInfo.deviceName = o.device.getName();
sourceDeviceInfo.deviceID = o.device.getDeviceID();
sourceDeviceInfo.deviceType = o.device.getType();
var destDeviceInfo = new midi.MIDIDeviceInfo();
destDeviceInfo.deviceName = midisynthInstance.getName();
destDeviceInfo.deviceID = midisynthInstance.getDeviceID();
destDeviceInfo.deviceType = midi.MIDI_DEVICE_SYNTHESIZER;
midi.stopStream(sourceDeviceInfo, destDeviceInfo);
Get file Play status
MIDI file playback status can be obtained by below API
Function | Description |
---|---|
getFilePlayStatus | Provides file playback status. |
ret = midi.getFilePlayStatus();
if (midi.MIDI_STREAM_STATUS_BUSY != ret) {
...
}
Set or get synthesizer parameter
MIDI supports getting or setting MIDI parameters for each of the channels. For example, you can set or get the volume of the MIDI channel
Function | Description |
---|---|
sendMessage | Sends a message from DTV widget to MIDI device. This is basically used to implement software MIDI controller. |
getInformation | Used for getting MIDI parameters such as volume, pitch bend, program, velocity etc.. for a specified MIDI channel. |
var evType = midi.MIDI_EVENT_CONTROL_CHANGE;
var evMsg = new midi.MIDIControlMessage();
evMsg.channel = MidiUI.channelList.activeItem.value;
evMsg.parameter = midi.MIDI_CC_BANK_SELECT_LSB;
evMsg.value = Number(i.value.bankNum);
var ret = midisynthInstance.sendMessage(evType, evMsg);
var evType = midi.MIDI_EVENT_PROGRAM_CHANGE;
var evMsg = new midi.MIDIControlMessage();
evMsg.channel = MidiUI.channelList.activeItem.value;
evMsg.parameter = 44;
evMsg.value = Number(i.value.programNum);
var ret = midisynthInstance.sendMessage(evType, evMsg);
var getChannelVolume = function(i){
var evType = midi.MIDI_EVENT_CONTROL_CHANGE;
var evMsg = new midi.MIDIControlMessage();
evMsg.channel = i;
evMsg.parameter = midi.MIDI_CC_CHANNEL_VOLUME_MSB;
evMsg.value = 00;
return midisynthInstance.getInformation(evType, evMsg);
};
Warning
This module is only supported on Samsung Smart TV models for 2013 and later. Samsung SDK 4.0 or higher could be used for development of MIDI applications.