urMus - Audio and Media Interactions and Interfaces on Mobile Phones


urMus

API Documentation

Global API functions

This page documents functions and variables that can be found in the global name space.

Debug Printing API

DPrint

Synopsis

DPrint("output")

Description

Debug print a give string in the center of the screen. This will also be used for system errors and should not be used for normal user interactions.

Arguments

RunScript

Synopsis

RunScript("script")

Description

Execute a string as Lua code.

Arguments

Timing API

Time

Synopsis

seconds = Time()

Description

Returns the system uptime of the host machine in seconds, with millisecond precision.

Returns

urSound FlowBox API

StartAudio

Synopsis

StartAudio()

Description

Starts the audio engine. Audio-related events will start working.

PauseAudio

Synopsis

PauseAudio()

Description

Pauses the audio engine. Audio-related events will not work while paused.

FlowBox

Synopsis

flowbox = FlowBox("type", "name", inheritedFlowbox)

Description

Creates a new instance of a specified flowbox. To seed cloning use global instances of flowboxes via _G["FB"..objectname].

Arguments

Returns

SourceNames

Synopsis

source1, source2, ... = SourceNames()

Description

Returns the names of all source objects offered by the urSound engine. Related flowbox variables can be accessed via _G["FB"..object1].

Returns

ManipulatorNames

Synopsis

manipName1, manipName2, ... = ManipulatorNames()

Description

Returns the names of all manipulator objects offered by the urSound engine. Related flowbox variables can be accessed via _G["FB"..manipName].

Returns

SinkNames

Synopsis

sinkName1, sinkName2, ... = SinkNames()

Description

Returns the names of all sink objects offered by the urSound engine. Related flowbox variables can be accessed via _G["FB"..sinkName].

Returns

File system helper API

DocumentPath

Synopsis

documentPath = DocumentPath("filename")

Description

If the file exists in the document path, returns the absolute path to the given file. If the file doesn't exist, throws an error.

Arguments

Returns

SystemPath

Synopsis

systemfilename = SystemPath("filename")

Description

Converts a relative filename to include an iPhone-project's resource path.

Arguments

Returns

2D Interface and Interaction API (aka urLook)

SetFrameRate

Synopsis

SetFrameRate(fps)

Description

Sets the maximum frames per second. Effective FPS may be lower if load is high.

Arguments

Page

Synopsis

page = Page()

Description

Returns the number index of the currently active page.

Returns

SetPage

Synopsis

SetPage(pageIndex)

Description

Sets the currently active page. Only frames created within an active page will be rendered. This allows for multiple mutually exclusive pages to be prepared and selectively rendered. Mouse events and other interface actions and events will only work for the currently active page.

Arguments

NumMaxPages

Synopsis

maxpages = NumMaxPages()

Description

Maximum number of pages supported by the current urMus built.

Returns

Region

Synopsis

newRegion = Region(["regionType", "regionName", parentRegion])

Description

Creates a rectangular region.

Arguments

Returns

NumRegions

Synopsis

num = NumRegions()

Description

Returns the current number of regions inside of the current page.

InputFocus

Synopsis

region = InputFocus()

Description

Returns the region that is currently receiving input events. The region must have EnableInput(true).

HasInput

Synopsis

isOver = HasInput(region, [topOffset, bottomOffset, leftOffset, rightOffset])

Description

Determines whether or not the input is over the specified region.

Arguments

Returns

InputPosition

Synopsis

x, y = InputPosition()

Description

Returns the input device's position on the screen.

Returns

ScreenHeight

Synopsis

screenHeight = ScreenHeight()

Description

Returns the height of the window in pixels. For an iPhone this is 480.

Returns

ScreenWidth

Synopsis

screenWidth = ScreenWidth()

Description

Returns the width of the window in pixels. For an iPhone this is 320.

Returns

Camera API (aka urLook more)

SetActiveCamera

Synopsis

SetActiveCamera(camera)

Description

Sets the active camera. Allows to pick between multiple cameras if they are present (front-facing, back-facing)

Arguments

ActiveCamera

Synopsis

camera = ActiveCamera()

Description

Returns which camera is currently active.

Returns

SetTorchFlashFrequency

Synopsis

SetTorchFlashFrequency(frequency)

Description

Sets the flashing frequency of the camera flash-light if present.

Arguments

Networking API

IPAddress

Synopsis

host = IPAddress()

Description

Returns the IP-address of the device.

StartHTTPServer

Synopsis

host, port = StartHTTPServer()

Description

Starts the HTTP Server which provides the web-based urMus programming environment. Returns the hostname and port of the service.

Returns

StopHTTPServer

Synopsis

StopHTTPServer()

Description

Stops the HTTP Server which provides the web-based urMus programming environment.

HTTPServer

Synopsis

name, port = HTTPServer()

Description

Returns the name and port of the HTTPServer run on the device.

Returns

StartOSCListener

Synopsis

host, port = StartOSCListener()

Description

Starts the OSC Listening service, which allows for incoming OSC message to be received. The event OnOSCMessage will be triggered when a message is received.

Returns

StopOSCListener

Synopsis

StopOSCListener()

Description

Stops the OSC Listening service.

SetOSCPort

Synopsis

SetOSCPort(port)

Description

Sets the OSC port of the OSCListening service, if it is running.

Arguments

OSCPort

Synopsis

port = OSCPort()

Description

Returns the current port of the OSCListener.

Returns

SendOSCMessage

Synopsis

SendOSCMessage(host, port, oscpattern, arg1, [arg2, ...])

Description

Sends an OSC message constiting of an arbitrary number of arguments which can be numbers or strings.

Arguments

StartNetAdvertise

Synopsis

StartNetAdvertise(id, port)

Description

Starts the ZeroConf service allowing a named id to be discovered by other devices on the local network.

Arguments

StartNetDiscovery

Synopsis

StartNetDiscovery(id)

Description

Starts the ZeroConf service discovery, allowing to find if the service with a specific ID is present or not. Will trigger OnNetConnect when the service appears and OnNetDisconnect when the service disappears.

Arguments

urMus API Overview