Sound ~ Sound Module Design Document

Introduction

This document will outline how new sound modules of will be designed to load, play and manipulate sound in-game using an open source library called SDL library.

SDL Library

SDL library is a cross-platform development library designed to provide low level access to audio, keyboard, mouse, joystick, and graphics hardware via OpenGL and Direct3D. More information could be found here.

Main Sound Structure

• a simple SDL Audio library that will be used to load/play sound file
• for the sound to play, your team needs to have your sound in an 'mp3' format if it is music, and/or a 'wav' format if it is a sound effect
• declare a sound_t variable
• make sure to put the name and type of file in this variable (SOUND or BACKGROUND_EFFECT)
• if a sound is associated with an action, the sound_t variable should be declared and freed within the function
• additionally, there are two types of arrays 'Mix_Chunk' and 'Mix_Music'
  • Mix_Chunk is for sound effects in which multiple effects may not be played at the same time
  • Mix_Music is for background music in which only one sound could be played at a time
• if you are in a situation with lots of sounds needed, we recommend creating a folder inside your 'src' folder that specifically hoards the files
• load the sound in this way, and it should run smoothly (see major drawbacks for error handling as well)

 typedef struct{
     // type of sound
     SoundType type;
     // name of sound
     char* name;
     // wav file information
     SDL_AudioSpec wavSpec;
     uint32_t wavLength;
     uint8_t *wavBuffer;
     //below for hash table
     int id; 
     // makes struct hashable
     UT_hash_handle hh; 
 } sound_t;

The current sound structure includes SoundType type, name, File_type, wavSpec, wavLength, wavBuffer, id, hh. SoundType will define whether the sound is for background or sound effect, as defined as

typedef enum {BACKGROUND, SOUND_EFFECT} SoundType;

Name will be the name of the sound file. wavSpec is SDL structure that describes the wav information of the wav sound file. wavLength describes the length of the sound file. wavBuffer is where the audio buffer will be stored. id and hh are used for hash table.

Modules

Load & Save Module

This module will initialize and dynamically allocate memory for the structs we will be using in our Game Sound and Edit Sound modules. We will include function to sve

functions:

'''
loads sound 
Inputs: 
- raw_file: probably .wav format 
returns: 
- sound_t* struct 
'''
hash_t* load_sound (raw_file); 


'''
frees sound 
Inputs: 
- sound_t* sound to free 
'''
void sound_free(sound_t* sound); 




## Game Sound Module:
This module will provide functions that play and pause the loaded sounds in game.


### Functions:
play sound
Inputs: Sound struct
Returns: Plays the sound file in the given struct

```C
'''
Plays sound 
Input: 
delay (int): time to delay before playing the sound when the function is called
sound: (char*) the hash id of the sound 
'''
void play_sound(char* sound, int delay); 

pause sound Inputs: Sound to be paused Returns: Pauses the sound

Edit Sound Module:

The purpose of this module is to manipulate the sound properties, including Path_to_sound_file, File_type, Duration, Name.

'''
set a new volume for the sound
Inputs: 
- sound_t* sound: the sound to change volume for
- volume: the volume to be set
'''
void set_volume(sound_t* sound, volume); 


'''
get the volume for the sound 
Inputs: 
- sound_t* sound: the sound 
Outpus: 
- integer representing volume 
'''
int get_volume(sound_t* sound);


'''
clip a duration of sound 
Inputs: 
- sound_t* sound: the original sound 
- start: start time of the new sound 
- end: end time of the new sound 
Returns:
- sound_t*: new sound object with clipped duration 
'''
sound_t* clip_sound(sound_t* sound, int start, int end); 
(note: start, end maye not be in form of int but some time-related struct) 

Hashtable

Hash table will be used to store Sound structs information. To implement the hash table, uthash.h will be used. More information could be achieved from here.

Hash Table Structure

The hash table of Sound struct will look like the following.

U hash tutorial struct:
#include “uthash.h”

struct my_struct {
    int id;                    /* key */
    char name[10];
    UT_hash_handle hh;         /* makes this structure hashable */
};

Hash Table Function

find_sound() finds the sound

//If we are using a key of type int, use HASH_FIND_INT macro 
//To find a sound struct in a hash with an int key:
struct my_struct *find_sound(int sound_id) {
    struct my_struct *s;

    HASH_FIND_INT(sound_hashtable, &sound_id, s);  /* s: output pointer */
    return s;
}

Major Drawbacks

The primary issue with playing sound was our struggle with the CS linux servers and trying to write code through the SSH connection. Multiple members were able to play sounds on our local devices but we were unable to replicate the result on our local machines to the CS server through SSH. Therefore, prior to writing any audio program, we recommend that your terminal can locate audio devices. On the Linux terminal, you can run

arecord -l

Similar commands for mac/Windows users are

system_profiler SPAudioDataType -xm

Get-CimInstance win32_sounddevice | fl *

This command will list all audio devices and sound cards installed in your computer. The primary error message we got when running this command on the CS Linux Servers was:

arecord: device_list:274: no soundcards found...

The output should look something like this:

$ arecord -l
**** List of CAPTURE Hardware Devices ****
card 0: I82801AAICH [Intel 82801AA-ICH], device 0: Intel ICH [Intel 82801AA-ICH]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 0: I82801AAICH [Intel 82801AA-ICH], device 1: Intel ICH - MIC ADC [Intel 82801AA-ICH - MIC ADC]
Subdevices: 1/1
Subdevice #0: subdevice #0

The error message from the CS Linux servers resulted from SSH being unable to access our local audio hardware.devices. A simple test to see if your audio works in SSH is to play a YouTube video. If sound cannot play, SSH most likely isn't using your computer's audio devices. The primary workaround was to install Virtuall Box and install a Linux image/CS Linux image and work through the Virtual Box.

More information can be found in the references page