Tutorial 28 - Codea v1.5.2: Objective C Add On, Audio

Figure 0. Codea Audio Player

28.1 Overview

CodeaAddon is an experimental protocol for adding native extensions to exported Codea projects. You must deal with Lua directly to register your functions and globals. This protocol should be considered alpha in version 1.5.2 and is subject to change in future Codea releases. If the protocol changes we will update the tutorial to reflect this.

As our first example we will demonstrate how to play an mp3 file from within Codea. iOS provides a number of mechanisms for implementing audio playback. The easiest technique from the perspective of the application developer is to use the AVAudioPlayer class which is part of the AV Foundation Framework. Apple recommends that you use this class for audio playback unless you are playing audio captured from a network stream or require very low I/O latency.

Upon instantiating an AVAudioPlayer class, the playback of audio may be controlled and monitored via the methods and properties available. Play, pause and stop methods may be used to control playback and the volume property may be used to adjust the volume level. The playing property may be used to determine whether or not the AVAudioPlayer object is currently playing audio. Using an audio player you can:

• Play sounds of any duration
• Play sounds from files or memory buffers
• Loop sounds
• Play multiple sounds simultaneously, one sound per audio player, with precise synchronisation
• Control relative playback level, stereo positioning, and playback rate for each sound you are playing
• Seek to a particular point in a sound file, which supports such application features as fast forward and rewind
• Obtain data you can use for playback-level metering

The AV Foundation framework supports the playback of a variety of different audio formats and codecs including both software and hardware based decoding. Codecs and formats currently supported are as follows:

• AAC (MPEG-4 Advanced Audio Coding)
• ALAC (Apple Lossless)
• AMR (Adaptive Multi-rate)
• HE-AAC (MPEG-4 High Efficiency AAC)
• iLBC (internet Low Bit Rate Codec)
• Linear PCM (uncompressed, linear pulse code modulation)
• MP3 (MPEG-1 audio layer 3)
• µ-law and a-law

Figure 1. Adding the AVFoundation Framework

You can optionally implement a delegate to handle interruptions (such as an incoming phone call), or if required update the user interface when a sound has finished playing.

28.2 Add the AVFoundation Framework to your App

Since the AVAudioPlayer class is part of the AV Foundation framework, it will be necessary to add this framework to the project. Fire up Xcode and load the exported version of your Codea application (See Tutorial 27). Click on the imported project file at the top left of the project navigator then in the Build Phases tab, scroll down to the link binary with libraries area and select the drop down arrow. Click on the "+" button below your existing frameworks to add a new framework. Find AVFoundation framework and click on "Add" (Figure 1).

Figure 2. MP3 File added to the Resource Group

28.3 Add the MP3 file to your Project

Any mp3 files that you want to play in your app need to be included in your project bundle. Adding these is simple. For our tutorial we generated a simple loop using Garage Band and then exported it to an mp3 file. Locate your mp3 and drag it from Finder to the Resources Group (folder) in the the Project Navigator of Xcode (Figure 2). We added a sub folder called Music (right click on the Resources Group and add a new Group) to contain the mp3 file but that is optional.

Figure 3. Adding a new Objective-C class.

28.4 Create our Custom Audio Add On Class

To create our new AudioAddOn class, right click on the Addons Group and select New File... from the pop up menu. Click on Cocoa Touch under iOS and make sure that Objective-C class has been selected (Figure 3), then click on Next.

Select Subclass of type NSObject and call the Class AudioAddOn. The two check boxes (Targeted for iPad and With XIB for user interface) should be greyed out. Click on Next, and then click on Create. Two new files will be added to the Addons Group, AudioAddOn.h and AudioAddOn.m.

The header file for our AudioAddOn class is mostly straight forward. We import the AVFoundation framework which we added above and the CodeaAddon class. AudioAddOn conforms to both the CodeaAddon and AVAudioPlayerDelegate protocols. We define a variable called audioAdOnInstance, which allows us to access Objective C methods from within our C functions playMusic() and stopMusic().

In the initialisation of this class we create our audio player object and assign our mp3 file to it. We also pre-buffer the mp3 file and set the number of loops to be infinite (by assigning a negative integer). At the end we assign audioAdOnInstance to self.

Some of the most used AVAudioPlayer delegate methods have been included, but we don't use them in this tutorial. The code is shown at the end of the tutorial.

28.5 Modifications to the Application Delegate

There are only minor changes to the Application Delegate files. We import our add on in the header file and create an instance variable which points to it (called audioAddOn).

In AppDelegate.mm we instantiate our add on class and then register the add on so we can use it in the Lua code.

To play your mp3 file from within your Lua code just call playMusic() and to stop it, call stopMusic(). Too easy!

	//
	// AppDelegate.h
	// LunarLander HD
	//
	// Created by Reefwing Software on Saturday, 13 April 2013
	// Copyright (c) Reefwing Software. All rights reserved.
	//
	#import <UIKit/UIKit.h>
	#import "AudioAddon.h"
	@class CodeaViewController;
	@interface AppDelegate : UIResponder <UIApplicationDelegate>
	@property (strong, nonatomic) AudioAddOn *audioAddOn;
	@property (strong, nonatomic) UIWindow *window;
	@property (strong, nonatomic) CodeaViewController *viewController;
	@end

view raw AppDelegate.h hosted with ❤ by GitHub

	//
	// AppDelegate.mm
	// LunarLander HD
	//
	// Created by Reefwing Software on Saturday, 13 April 2013
	// Copyright (c) Reefwing Software. All rights reserved.
	//
	#import "AppDelegate.h"
	#import "CodeaViewController.h"
	@implementation AppDelegate
	- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
	{
	self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
	self.viewController = [[CodeaViewController alloc] init];
	// Create and add our AudioAddOn to Codea
	self.audioAddOn = [[AudioAddOn alloc] init];
	[self.viewController registerAddon: self.audioAddOn];
	NSString* projectPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"LunarLanderHD.codea"];
	[self.viewController loadProjectAtPath:projectPath];
	self.window.rootViewController = self.viewController;
	[self.window makeKeyAndVisible];
	return YES;
	}
	- (void)applicationWillResignActive:(UIApplication *)application
	{
	}
	- (void)applicationDidEnterBackground:(UIApplication *)application
	{
	}
	- (void)applicationWillEnterForeground:(UIApplication *)application
	{
	}
	- (void)applicationDidBecomeActive:(UIApplication *)application
	{
	}
	- (void)applicationWillTerminate:(UIApplication *)application
	{
	}
	@end

view raw AppDelegate.mm hosted with ❤ by GitHub

	//
	// AudioAddOn.h
	// AudioDemo
	//
	// Created by David Such on 13/04/13.
	// Copyright (c) 2013 Reefwing Software. All rights reserved.
	//
	// Version: 1.0 - Original (13/04/13)
	// 1.1 - Volume control & monitoring added, metering enabled (14/04/14)
	#import <Foundation/Foundation.h>
	#import <AVFoundation/AVFoundation.h>
	#import "CodeaAddon.h"
	id audioAddOnInstance;
	// This class conforms to the CodeaAddon & AVAudioPlayerDelegate Protocols
	@interface AudioAddOn : NSObject<CodeaAddon, AVAudioPlayerDelegate>
	@property (strong, nonatomic) AVAudioPlayer *player;
	// Forward declare our Lua Audio functions. These are static to confine their scope
	// to this file. By default c functions are global.
	static int playMusic(struct lua_State *state);
	static int stopMusic(struct lua_State *state);
	static int getVolume(struct lua_State *state);
	static int setVolume(struct lua_State *state);
	static int peakPowerForChannel(struct lua_State *state);
	static int averagePowerForChannel(struct lua_State *state);
	@end

view raw AudioAddOn.h hosted with ❤ by GitHub

	//
	// AudioAddOn.m
	// AudioDemo
	//
	// Created by David Such on 13/04/13.
	// Copyright (c) 2013 Reefwing Software. All rights reserved.
	//
	// Version: 1.0 - Original (13/04/13)
	// 1.1 - Volume control & monitoring added, metering enabled (14/04/14)
	#import "AudioAddOn.h"
	#import "lua.h"
	@implementation AudioAddOn
	#pragma mark - Initialisation
	- (id)init
	{
	self = [super init];
	if (self)
	{
	// Initialise the Audio Player with your mp3 file.
	NSURL *url = [NSURL fileURLWithPath:[[NSBundle mainBundle]
	pathForResource:@"LunarLander"
	ofType:@"mp3"]];
	NSError *error;
	_player = [[AVAudioPlayer alloc] initWithContentsOfURL: url error: &error];
	if (error)
	NSLog(@"Error initialiasing Audio Add On: %@", [error localizedDescription]);
	else
	{
	// Player initialised, assign delegate to this class
	[_player setDelegate: self];
	// Calling prepareToPlay preloads buffers and acquires the audio hardware needed for playback,
	// which minimizes the lag between calling the play method and the start of sound output.
	[_player prepareToPlay];
	// A value of 0, which is the default, means to play the sound once. Set a positive integer
	// value to specify the number of times to return to the start and play again. For example,
	// specifying a value of 1 results in a total of two plays of the sound. Set any negative
	// integer value to loop the sound indefinitely until you call the stop method.
	[_player setNumberOfLoops: -1];
	// The default value for the meteringEnabled property is off (Boolean NO). Before using metering
	// for an audio player, you need to enable it by setting this property to YES.
	[_player setMeteringEnabled: YES];
	// audioAddOnInstance allows us to access self from within the c functions.
	audioAddOnInstance = self;
	}
	}
	return self;
	}
	#pragma mark - CodeaAddon Delegate
	// Classes which comply with the <CodeaAddon> Protocol must implement this method
	- (void) codea:(CodeaViewController*)controller didCreateLuaState:(struct lua_State*)L
	{
	NSLog(@"AudioAddon Registering Functions");
	// Register the Audio functions, defined below
	lua_register(L, "playMusic", playMusic);
	lua_register(L, "stopMusic", stopMusic);
	lua_register(L, "setVolume", setVolume);
	lua_register(L, "getVolume", getVolume);
	lua_register(L, "peakPowerForChannel", peakPowerForChannel);
	lua_register(L, "averagePowerForChannel", averagePowerForChannel);
	}
	// Optional method
	- (void) codeaWillDrawFrame:(CodeaViewController*)controller withDelta:(CGFloat)deltaTime
	{
	}
	#pragma mark - Audio Add On Functions and associated Methods
	// Objective C Methods
	- (void)startPlayer
	{
	[self.player play];
	}
	- (void)stopPlayer
	{
	if ([self.player isPlaying])
	[self.player stop];
	}
	- (void)setPlayerVolume: (int)setting
	{
	// The volume property is the playback gain for the AV audio player object,
	// it expects a float ranging from 0.0 through 1.0.
	//
	// Our Codea slider control returns an integer from 0 to 100 so we need to
	// convert this to a float in the appropriate range before applying it to
	// our player. As a defensive measure we will clamp the result between 0.0 and 1.0.
	float floatSetting = MAX(0.0f, MIN((float)setting / 100.0f, 1.0f));
	[self.player setVolume: floatSetting];
	}
	- (int)getPlayerVolume
	{
	return (self.player.volume * 100.0f);
	}
	- (int)getPeakPower: (NSUInteger)channel
	{
	if ([self.player isPlaying])
	{
	// Refresh the average and peak power values for all channels of our audio player.
	[self.player updateMeters];
	// Peak power is a floating-point representation, in decibels, of a given audio channel’s current peak power.
	// A return value of 0 dB indicates full scale, or maximum power while a return value of -160 dB indicates
	// minimum power (that is, near silence).
	//
	// If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0
	// (that is, it may enter the positive range).
	//
	// Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
	float power = -160.0f; // Initialise to silence
	if (channel <= [self.player numberOfChannels])
	power = [self.player peakPowerForChannel: channel];
	// Our dial is expecting a value between 0 and 100.
	if (power >= 0)
	return 100;
	else
	{
	power += 160.0f; // power is now a +ve float between 0 and 160
	power = (power / 160.0f) * 100.0f; // change to a percentage
	return (int)power;
	}
	}
	else
	return 0;
	}
	- (int)getAveragePower: (NSUInteger)channel
	{
	if ([self.player isPlaying])
	{
	// Refresh the average and peak power values for all channels of our audio player.
	[self.player updateMeters];
	// A floating-point representation, in decibels, of a given audio channel’s current average power.
	// A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates
	// minimum power (that is, near silence).
	//
	// If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0
	// (that is, it may enter the positive range).
	//
	// Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
	float power = -160.0f; // Initialise to silence
	if (channel <= [self.player numberOfChannels])
	power = [self.player averagePowerForChannel: channel];
	// Our dial is expecting a value between 0 and 100.
	if (power >= 0)
	return 100;
	else
	{
	power += 160.0f; // power is now a +ve float between 0 and 160
	power = (power / 160.0f) * 100.0f; // change to a percentage
	return (int)power;
	}
	}
	else
	return 0;
	}
	// C Functions
	//
	// Note that the returned value from all exported Lua functions is how many values that function should return in Lua.
	// For example, if you return 0 from that function, you are telling Lua that peakPowerForPlayer (for example) returns 0 values.
	// If you return 2, you are telling Lua to expect 2 values on the stack when the function returns.
	//
	// To actually return values, you need to push them onto the Lua stack and then return the number of values you pushed on.
	static int playMusic(struct lua_State *state)
	{
	[audioAddOnInstance startPlayer];
	return 0;
	}
	static int stopMusic(struct lua_State *state)
	{
	[audioAddOnInstance stopPlayer];
	return 0;
	}
	static int getVolume(struct lua_State *state)
	{
	// Push the integer volume onto the Lua stack
	lua_pushinteger(state, [audioAddOnInstance getPlayerVolume]);
	// Our function returns 1 value = volume
	return 1;
	}
	static int setVolume(struct lua_State *state)
	{
	[audioAddOnInstance setPlayerVolume: lua_tonumber(state, 1)];
	return 0;
	}
	static int peakPowerForChannel(struct lua_State *state)
	{
	// Channel numbers are zero-indexed. A monaural signal,
	// or the left channel of a stereo signal, has channel number 0.
	NSUInteger channel = lua_tonumber(state, 1);
	// Push the integer power onto the Lua stack
	lua_pushinteger(state, [audioAddOnInstance getPeakPower: channel]);
	// Our function returns 1 value = peak power
	return 1;
	}
	static int averagePowerForChannel(struct lua_State *state)
	{
	// Channel numbers are zero-indexed. A monaural signal,
	// or the left channel of a stereo signal, has channel number 0.
	NSUInteger channel = lua_tonumber(state, 1);
	// Push the integer power onto the Lua stack
	lua_pushinteger(state, [audioAddOnInstance getAveragePower: channel]);
	// Our function returns 1 value = peak power
	return 1;
	}
	#pragma mark - AVAudioPlayer Delegate
	// These Audio Player call back methods are not used in this tutorial but provided here
	// for information. There are a number of other delegate methods available. Check the
	// documentation.
	- (void)audioPlayerDidFinishPlaying:(AVAudioPlayer *)player successfully:(BOOL)flag
	{
	}
	- (void)audioPlayerDecodeErrorDidOccur:(AVAudioPlayer *)player error:(NSError *)error
	{
	NSLog(@"Error decoding audio file: %@", [error localizedDescription]);
	}
	-(void)audioPlayerBeginInterruption:(AVAudioPlayer *)player
	{
	}
	-(void)audioPlayerEndInterruption:(AVAudioPlayer *)player
	{
	}
	@end

view raw AudioAddOn.m hosted with ❤ by GitHub

	-- AudioDemo
	--
	-- Uses Cider Controls v1.6 from @Mark and @aciolino
	-- make sure you add this as a Dependency
	--
	-- Reefwing Software (c) 2013
	-- www.reefwing.com.au
	function setup()
	displayMode(FULLSCREEN)
	setInstructionLimit(0)
	ctlFrame = Control("Audio Player", 20, HEIGHT - 600, 450, HEIGHT - 20)
	ctlFrame.background = color(181, 141, 203, 255)
	ctlFrame.textAlign = CENTER
	ctlFrame.fontSize = 24
	-- Initialise the Cider Controls
	playBtn = TextButton("Play", 70, 480, 225, 520)
	stopBtn = TextButton("Stop", 245, 480, 400, 520)
	sldVolume = Slider("Volume Control", 70, HEIGHT - 450, 400, HEIGHT - 420, 0, 100, 50)
	-- Initialise the Cider Volume Indicators
	dial = Dial("Left", 70, 780, 220, 930, 0, 100, 0)
	doughnut = Doughnut("Right", 250, 780, 400, 930, 0, 100, sldVolume.val)
	doughnut.intervals = 25
	doughnut.warm = 9
	doughnut.hot = 13
	end
	function draw()
	-- This sets a dark background color
	background(178, 173, 173, 255)
	-- Draw the Cider Controls
	ctlFrame:draw()
	playBtn:draw()
	stopBtn:draw()
	sldVolume:draw()
	dial:draw()
	doughnut:draw()
	-- Update the dB Meter Dials
	--
	-- The iPad should have 2 channels, left = 0 and right = 1
	dial.val = averagePowerForChannel(0) or 0
	doughnut.val = averagePowerForChannel(1) or 0
	end
	function touched(touch)
	if sldVolume: touched(touch) then
	-- call AudioAddOn function
	setVolume(sldVolume.val)
	end
	if playBtn:touched(touch) then
	-- call AudioAddOn function
	playMusic()
	end
	if stopBtn:touched(touch) then
	-- call AudioAddOn function
	stopMusic()
	end
	end

view raw Main.lua hosted with ❤ by GitHub