4.4. ISMCBBuilder

added in version 1.12.0

This interface provides the function which creates melody speaker control commands.

This interface is only for models which support a melody speaker and for FVP10.For the supporting models, refer to Supported Peripherals .

  • Property

    Name

    Contents

    commands

    Generated commands.

  • Method

    Name

    Contents

    appendSoundWithSetting

    The command for playback of a sound registered in the melody speaker is generated and added to the command buffer.

    appendSoundWithSound

    A command for playback of the sound data specified by the argument is generated and added to the command buffer.

4.4.1. SMCBSoundStorageArea

added in version 1.12.0

Constant that specifies the sound storage area.

  • Declaration

    typedef NS_ENUM(NSUInteger, SMCBSoundStorageArea) {
        SMCBSoundStorageArea1,
        SMCBSoundStorageArea2
    };
    

The sound storage areas which correspond to the constants are the following.

MelodySpeakerModel Constants Sound storage area
StarIoExtMelodySpeakerModelMCS10
SMCBSoundStorageArea1
SMCBSoundStorageArea2
Sound storage area1
Sound storage area2
StarIoExtMelodySpeakerModelFVP10
SMCBSoundStorageArea1
SMCBSoundStorageArea2
Default area
User area

4.4.2. commands

added in version 1.12.0

Gets the command buffer (generated command).

  • Declaration

    @property (nonatomic, readonly) NSMutableData *commands;
    
  • Parameter

    None

  • Return value

    Contents Type
    Cmmand buffer (generated command) NSMutableData *

4.4.3. appendSoundWithSetting

added in version 1.12.0

The command for playback of a sound registered in the melody speaker is generated and added to the command buffer.

  • Declaration

    - (void)appendSoundWithSetting:(nullable SMSoundSetting *)setting error:(nullable NSError **)error;
    
  • Parameter

    Name Contents Type
    setting Settings information for the playback sound (sound storage area, sound number, etc.) SMSoundSetting
    error Error information when command generation failed NSError *

    The parameters which can be set in the setting argument are the following.

    StarIoExtMelodySpeakerModel

    Property

    Contents

    Parameters that can be set

    Default (operation when nothing is specified)

    StarIoExtMelodySpeakerModelMCS10

    soundStorageArea

    Sound storage area

    SMCBSoundStorageArea1

    Use the MCS10 unit DIP switch settings.

    SMCBSoundStorageArea2

    soundNumber

    Sound number

    0 - 7

    Use the MCS10 unit DIP switch settings.

    volume

    Volume

    0 – 15

    Use the MCS10 unit DIP switch settings.

    SMSoundSettingVolumeOff

    SMSoundSettingVolumeMax

    SMSoundSettingVolumeMin

    StarIoExtMelodySpeakerModelFVP10

    soundStorageArea

    Sound storage area

    SMCBSoundStorageArea1

    SMCBSoundStorageArea1

    SMCBSoundStorageArea2

    soundNumber

    Sound number

    1 - 255 1

    count

    Count

    1 - 65535 1

    delay

    Delay time (1 sec units)

    0 - 65535 0

    interval

    Interval time (1 sec units)

    0 - 65535 0

    Sound played according to the combination of parameters specified for the soundStorageArea property and soundNumber property are as follows.

    StarIoExtMelodySpeakerModel

    soundStorageArea

    soundNumber

    Sound

    StarIoExtMelodySpeakerModelMCS10

    SMCBSoundStorageArea1

    0

    Sound1

    1

    Sound2

    2

    Sound3

    3

    Sound4

    4

    Sound5

    5

    Sound6

    6

    Sound7

    7

    Sound8

    SMCBSoundStorageArea2

    0

    Sound9

    1

    Sound10

    2

    Sound11

    3

    Sound12

    4

    Sound13

    5

    Sound14

    6

    Sound15

    7

    Sound16

    StarIoExtMelodySpeakerModelFVP10

    SMCBSoundStorageArea1

    1 - 255

    Sound stored in the specified sound number of the default area

    SMCBSoundStorageArea2

    1 - 255

    Sound stored in the specified sound number of the user area

  • Return value

    None

  • Error code

    Value Contents
    SMResultCodeInvalidArgument
    One of the following
    1. The property that can not be set on the specified model is set.
    2. Only one of the soundStorageArea property and the soundNumber property is set.
    SMResultCodeArgumentOutOfRange Parameter is out of range
  • Examples

    + (NSData *)createPlayingRegisteredSound:(StarIoExtMelodySpeakerModel)model
                                specifySound:(BOOL)specifySound
                            soundStorageArea:(SMCBSoundStorageArea)soundStorageArea
                                soundNumber:(NSInteger)soundNumber
                                specifyVolume:(BOOL)specifyVolume
                                    volume:(NSInteger)volume
                                        error:(NSError * _Nullable * _Nullable) error {
        ISMCBBuilder *builder = [StarIoExt createMelodySpeakerCommandBuilder:model];
    
        SMSoundSetting *setting = [SMSoundSetting new];
    
        if (specifySound == YES) {
        [setting setSoundStorageArea:soundStorageArea];
        [setting setSoundNumber:soundNumber];
        }
    
        if (specifyVolume == YES) {
        [setting setVolume:volume];
        }
    
        [builder appendSoundWithSetting:setting error:error];
    
        if (*error != nil) {
        return nil;
        }
    
        return [builder.commands copy];
    }
    

    Refer to MelodySpeakerFunctions.m

4.4.4. appendSoundWithSound

added in version 1.12.0

A command for playback of the sound data specified by the argument is generated and added to the command buffer.

Warning

StarIoExtMelodySpeakerModelFVP10 is not supported.

  • Declaration

    - (void)appendSoundWithSound:(nonnull NSData *)data (nullable SMSoundSetting *)setting error:(nullable NSError **)error;
    
  • Parameter

    Name Contents Type
    data Sound data NSData *
    setting Settings information for the playback sound (sound storage area, sound number, etc.) SMSoundSetting
    error Error information when command generation failed NSError *

    For the supported sound formats, refer to the table of supported sound formats.

    Name Value
    Sound file format WAV
    WAV file format Linear PCM
    Sampling rate 12800Hz
    Bit depth 16 bits or 8 bits
    Channel Monaural
    Playback time
    Max. 5 sec when bitdepth is 16
    Max. 10 sec when bitdepth is 8

    1. It is possible to convert a sound file format to a format in the table of supported sound formats by using the Start Sound Converter application that was provided with this package. For details, refer to “FileFormatList_en.htm” in “Others/StarSoundConverter/(Windows or Mac)/Documents” folder.

    The parameters which can be set in the setting argument are the following.

    Property Contents Parameters that can be set Default (operation when nothing is specified)
    volume Volume
    0 – 15
    SMSoundSettingVolumeOff
    SMSoundSettingVolumeMax
    SMSoundSettingVolumeMin
    Use the MCS10 unit DIP switch settings.
  • Return value

    None

  • Error code

    Value Contents
    StarIoExtErrorFormatError Data other than a supported sound format is input.
    SMResultCodeInvalidArgument The property that can not be set on the specified model is set.
    SMResultCodeArgumentOutOfRange Parameter is out of range
    StarIoExtErrorInvalidOperation StarIoExtMelodySpeakerModelFVP10 is specified.
  • Examples

    + (NSData *)createPlayingReceivedData:(StarIoExtMelodySpeakerModel)model
                                filePath:(NSString *)filePath
                            specifyVolume:(BOOL)specifyVolume
                                    volume:(NSInteger)volume
                                    error:(NSError * _Nullable * _Nullable)error {
        ISMCBBuilder *builder = [StarIoExt createMelodySpeakerCommandBuilder:model];
    
        SMSoundSetting *setting = [SMSoundSetting new];
    
        NSURL *fileUrl = [[NSURL alloc] initWithString:filePath];
    
        NSData *fileData = [[NSData alloc] initWithContentsOfURL:fileUrl];
    
        if (specifyVolume == YES) {
        [setting setVolume:volume];
        }
    
        [builder appendSoundWithSound:fileData setting:setting error:error];
    
        if (*error != nil) {
        return nil;
        }
    
        return [builder.commands copy];
    }
    

    Refer to MelodySpeakerFunctions.m