Working with Multimedia API

Working with Multimedia

The Android SDK provides a variety of methods for applications to incorporate audio and visual media,
including support for many different media types and formats. Individual Android devices and developers can
extend the list of supported media to other formats. Not every Android handset has the same multimedia
capabilities.Always verify the capabilities of target devices before publication.

The multimedia features of the Android platform generally fall into three categories: ∙
Still images (recorded with the camera)
∙ Audio (recorded with the microphone, played back with speakers or audio output) ∙ Video (recorded
with the camera and microphone, played back with speakers or audio output)

Multimedia hardware such as a built-in camera, speakers, and audio or video output ports are optional features
for Android devices.

In addition to requiring the appropriate permissions, you can specify which optional features your application
requires within the Android Manifest file.You can do this using the <uses-feature> tag of the Android Manifest
file declare that your application uses the camera. Remember, though, that the <uses feature> tag is not enforced
by the Android platform. Instead, application stores such as the Android Market use this data to filter which
applications to sell to certain devices.

Any application that requests the CAMERA permission is assumed to use all camera features. If your application
accesses the camera, but can function properly without it, you can also set the android:required field of
<uses-feature> to false.However, if your application requires a microphone and a camera with autofocus but not
a flash to be present on the device, you can set the camera features your application requires specifically, like
this:
<uses-feature android:name ”android.hardware.microphone” />
<uses-feature android:name ”android.hardware.camera” />
<uses-feature android:name ”android.hardware.camera.autofocus” />

Working with Still Images

Capturing Still Images Using the Camera
The Camera object (android.hardware.Camera) controls the camera on handsets that have camera support
enabled.The preview feature of the camera relies on the assignment of a SurfaceHolder of an appropriate
type.This enables applications to control the placement and size of the preview area that the camera can use.
Follow these steps to add camera capture capability to an application without having to draw preview frames (the
CameraSurfaceView displays the camera view):
1. Create a new class extending SurfaceView and implement SurfaceHolder.Callback. For this example,we
name this class CameraSurfaceView.
2. In the surfaceCreated() method, get an instance of the Camera object.
3. In the surfaceChanged() method, configure and apply the Camera.Parameters; then call the startPreview()
method.
4. Add a method in CameraSurfaceView for capturing images.
5. Add the CameraSurfaceView to an appropriate layout.
6. Include some way, such as a button, for the user to trigger the capturing of images. 7.
Implement a PictureCallback class to handle storing of the captured image.
8. Add the android.permission.CAMERA permission to the AndroidManifest.xml file. 9.
Release the Camera object in the surfaceDestroyed() method.
Configuring Camera Mode Settings
You can use the Camera class to configure the specific capture settings for a picture. Many of the capture settings
are stored in the Camera.Parameters class, and set in the Camera using the setParameters() method.
Working with Common Camera Parameters
Let’s take a closer look at the Camera.Parameters class. Some of the most interesting camera parameters are ∙
 Flash modes (where flash hardware is available)
∙ Focus types (fixed point, depth of field, infinity, and so on)

∙ White balance settings (fluorescent, incandescent, and so on)

∙ Scene modes (snow, beach, fireworks, and so on)

∙ Effects (photo negative, sepia, and so on)

∙ Anti-banding settings (noise reduction)

Different parameters are supported by different devices, so always check for support before trying to enable
parameters. Use the Camera.Parameters class to determine what camera features are supported. For example, you
can use the set of methods called getSupportedFlashModes(), getSupportedFocusModes(), and so on.Also, the
Camera.Parameters class contains methods to access more technical camera settings, such
as exposure compensation and EXIF information.

Zooming the Camera

The camera zoom setting is controlled using the startSmoothZoom() and stopSmoothZoom() methods of the
Camera class.As you might expect, you can set zoom parameters using the Camera.Parameters class. Useful
zoom methods in the Camera.Parameters class include
∙ Determining if zooming is supported with isZoomSupported()

∙ Determining if smooth zooming is supported with isSmoothZoomSupported()

∙ Determining the maximum zoom value with getMaxZoom()

∙ Retrieving the current zoom value with getZoom()

∙ Setting the current zoom value with setZoom()

∙ Calculating the zoom increments (for example, 1x, 2x, 10x) with getZoomRatios()
Depending on the features available for a specific camera, zoom might be digital, optical, or
some combination of the two.

Sharing Images
Storing an image in the local application directory, as demonstrated, might work for some applications; however,
other applications might find it useful if the image goes in the shared image library on the device.The
ContentResolver can be used in conjunction with the MediaStore object to push the image into the shared image
library.The following example demonstrates storing the still image taken by the camera as an image file within
the MediaStore content provider, using the same camera image callback:

Working with Video

In recent years, video has become commonplace on handsets. Most handsets on the market now can record and
play back video, and this is no different with Android, although the specific video features might vary from
handset to handset.

Recording Video
Android applications can record video using the MediaRecorder class. Using MediaRecorder is a matter of
following a few simple steps:
1. Instantiate a new MediaRecorder object.
2. Set the video source.
3. Set the video output format.
4. Set the video size to record (optional).
5. Set the video frame rate (optional).
6. Set the video encoder.
7. Set the file to record to. (The extension must match output format.)
8. Set the preview surface.
9. Prepare the object for recording.
10. Start the recording.
11. Stop and release the recording object when finished.
Playing Video
The simplest way to play back video with the Android SDK is to use the VideoView widget along with the
MediaController widget to provide basic video controls.The following is an implementation of an onCreate()
method within an Activity that demonstrates a workable video playback solution:

Working with Audio

Much like video, the Android SDK provides methods for audio playback and recording. Audio files can be
resources, local files, or Uri objects to shared or network resources.Audio recording takes place through the
built-in microphone on the device, if one is present (typically a requirement for a phone because one speaks into
it quite often).

Recording Audio
The MediaRecorder object of the Android SDK provides audio recording functionality. Using it is a matter of
following a few simple steps you should now find familiar:
1. Instantiate a new MediaRecorder object.
2. Set the audio source.
3. Set the audio format to record with.
4. Set the file format to store the audio in.
5. Set the file to record to.
6. Prepare the object for recording.
7. Start the recording.
8. Stop and release the recording object when finished.

Playing Audio
The MediaPlayer object can be used to play audio.The following steps are required to prepare a file for playback:
1. Instantiate a new MediaPlayer object.
2. Set the path to the file using the setDataSource method.
3. Call the prepare() method of the MediaPlayer object.
4. Call the start() method to begin playback.
5. Playback can then be stopped with a call to the stop() method.

Using Android Telephony APIs

Working with Telephony Utilities
The Android SDK provides a number of useful utilities for applications to integrate phone features available on
the device. Generally speaking, developers should consider an Android device first and foremost as a
phone.Although these devices might also run applications, phone operations generally take precedence.Your
application should not interrupt a phone conversation, for example.To avoid this kind of behavior, your
application should know something about what the user is doing, so that it can react differently. For
instance, an application might query the state of the phone and determine that the user is talking on the phone
and then choose to vibrate instead of play an alarm.

In other cases, applications might need to place a call or send a text message. Phones typically support a Short
Message Service (SMS), which is popular for texting (text messaging). Enabling the capability to leverage this
feature from an application can enhance the appeal of the application and add features that can’t be easily
replicated on a desktop environment. Because many Android devices are phones, applications frequently deal
with phone numbers and the contacts database; some might want to access the phone dialer to place calls or
check phone status information.Adding telephony features to an application enables a more integrated user
experience and enhances the overall value of the application to the users.
Gaining Permission to Access Phone State Information
Let’s begin by looking at how to determine telephony state of the device, including the ability to request the hook
state of the phone, information of the phone service, and utilities for handling and verifying phone numbers.The
TelephonyManager object within the android.telephony package is a great place to start.

Many of the method calls in this section require explicit permission set with the Android application manifest
file.The READ_PHONE_STATE permission is required to retrieve information such as the call state, handset
phone number, and device identifiers or serial numbers.The ACCESS_COARSE_LOCATION permission is
required for cellular location information.

The following block of XML is typically needed in your application’s AndroidManifest.xml file to access basic
phone state information:
<uses-permission
android:name ”android.permission.READ_PHONE_STATE” />

Requesting Call State

You can use the TelephonyManager object to retrieve the state of the phone and some information about the
phone service itself, such as the phone number of the handset.
You can request an instance of TelephonyManager using the getSystemService() method, like this:
TelephonyManager telManager (TelephonyManager)
getSystemService(Context.TELEPHONY_SERVICE);
With a valid TelephonyManager instance, an application can now make several queries. One important method is
getCallState().This method can determine the voice call status of the handset.The following block of code shows
how to query for the call state and all the possible return values:
int callStatus telManager.getCallState();
String callState null;
switch (callStatus) {
case TelephonyManager.CALL_STATE_IDLE:
callState “Phone is idle.”;
break;
case TelephonyManager.CALL_STATE_OFFHOOK:
callState “Phone is in use.”;
break;
case TelephonyManager.CALL_STATE_RINGING:
callState “Phone is ringing!”;
break;
}
Log.i(“telephony”, callState);

Requesting Service Information

In addition to call and service state information, your application can retrieve other information about the
device.This information is less useful for the typical application but can diagnose problems or provide
specialized services available only from certain provider networks.
The following code retrieves several pieces of service information:
String opName telManager.getNetworkOperatorName();
Log.i(“telephony”, “operator name “ + opName);
String phoneNumber telManager.getLine1Number();
Log.i(“telephony”, “phone number “ + phoneNumber);
String providerName telManager.getSimOperatorName();
Log.i(“telephony”, “provider name “ + providerName);
Monitoring Signal Strength and Data Connection Speed
Sometimes an application might want to alter its behavior based upon the signal strength or service type of the
device. For example, a high-bandwidth application might alter stream quality or buffer size based on whether the
device has a low-speed connection (such as 1xRTT or EDGE) or a high-speed connection (such as EVDO or
HSDPA). TelephonyManager can be used to determine such information.

Working with Phone Numbers

Applications that deal with telephony, or even just contacts, frequently have to deal with the input, verification,
and usage of phone numbers.The Android SDK includes a set of helpful utility functions that simplify handling
of phone number strings.Applications can have phone numbers formatted based on the current locale setting. For
example, the following code uses the formatNumber() method:
String formattedNumber
PhoneNumberUtils.formatNumber(“9995551212”);
Log.i(“telephony”, formattedNumber);

Using SMS
SMS usage has become ubiquitous in the last several years. Integrating messaging services, even if only
outbound, to an application can provide familiar social functionality to the user. SMS functionality is provided to
applications through the android.telephony package.

Gaining Permission to Send and Receive SMS Messages

SMS functionality requires two different permissions, depending on if the application sends or receives
messages.The following XML, to be placed with AndroidManifest.xml, shows the permissions needed for both
actions:
<uses-permission
android:name ”android.permission.SEND_SMS” />
<uses-permission
android:name ”android.permission.RECEIVE_SMS” />

Sending an SMS
To send an SMS, an application first needs to get an instance of the SmsManager. Unlike other system services,
this is achieved by calling the static method getDefault() of SmsManager: final SmsManager sms
SmsManager.getDefault();
Now that the application has the SmsManager, sending SMS is as simple as a single call:
sms.sendTextMessage( “9995551212”, null, “Hello!”, null, null);

Receiving an SMS
Applications can also receive SMS messages.To do so, your application must register a BroadcastReceiver to
listen for the Intent action associated with receiving an SMS.An application listening to SMS in this way doesn’t
prevent the message from getting to other applications.
Expanding on the previous example, the following code shows how any incoming text message can be placed
within a TextView on the screen:
final TextView receivedMessage (TextView)findViewById(
R.id.received_message);

Making and Receiving Phone Calls

It might come as a surprise to the younger generation (they usually just text), but phones are often still used for
making and receiving phone calls.Any application can be made to initiate calls and answer incoming calls;
however, these abilities should be used judiciously so as not to unnecessarily disrupt the calling functionality of
the user’s device.
Making Phone Calls
You’ve seen how to find out if the handset is ringing. Now let’s look at how to enable your application to make
phone calls as well.
Building on the previous example, which sent and received SMS messages,we now walk through similar
functionality that adds a call button to the screen to call the phone number instead of messaging it. The Android
SDK enables phone numbers to be passed to the dialer in two different ways.The first way is to launch the dialer
with a phone number already entered.The user then needs to press the Send button to actually initiate the
call.This method does not require any specific permissions.The second way is to actually place the call.This
method requires the android.permission.CALL_PHONE permission to be added to the application’s
AndroidManifest.xml file.

We extract the phone number the user entered in the EditText field (or the most recently received SMS when
continuing with the previous example).The following code demonstrates how to launch the dialer after the user
presses the Call button:
Button call (Button) findViewById(R.id.call_button);
 call.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
Uri number Uri.parse(“tel:” +
numberEntry.getText().toString());
Intent dial new Intent(
Intent.ACTION_DIAL, number);
startActivity(dial);
}
});

Receiving Phone Calls

Much like applications can receive and process incoming SMS messages, an application can register to answer
incoming phone calls.To enable this within an application, you must implement a broadcast receiver to process
intents with the action Intent.ACTION_ANSWER.
Remember, too, that if you’re not interested in the call itself, but information about the incoming call, you might
want to consider using the CallLog.Calls content provider (android.provider.CallLog) instead.You can use the
CallLog.calls class to determine recent call information, such as
∙ Who called

∙ When they called

∙ Whether it was an incoming or outgoing call

∙ Whether or not anyone answered

∙ The duration of the call

Working with Notifications

Notifying the User
Applications can use notifications to greatly improve the user’s experience. For example: n An email application
might notify a user when new messages arrive.A news reader application might notify a user when there are new
articles to read.
∙ A game might notify a user when a friend has signed in, or sent an invitation to play, or beat a high score.

∙ A weather application might notify a user of special weather alerts.

∙ A stock market application might notify the user when certain stock price targets are met. (Sell now! Before
it’s too late!)

Users appreciate these notifications because they help drive application workflow, reminding the users when they
need to launch the application. However, there is a fine line between just enough and too many
notifications.Application designers need to consider carefully how they should employ the use of notifications so
as not to annoy the user or interrupt them without good reason. Each notification should be appropriate for the
specific application and the event the user is being notified of. For example, an
application should not put out an emergency style notification (think flashing lights, ringing noises, and generally
making a “to-do”) simply to notify the user that his picture has been uploaded to a website or that new content
has been downloaded.
The Android platform provides a number of different ways of notifying the user. Notifications are often
displayed on the status bar at the top of the screen. Notifications may involve
∙ Textual information

∙ Graphical indicators
 ∙ Sound indicators

∙ Vibration of the device

∙ Control over the indicator light

Notifying with the Status Bar

The standard location for displaying notifications and indicators on an Android device is the status bar that runs
along the top of the screen.Typically, the status bar shows information such as the current date and time. It also
displays notifications (like incoming SMS messages) as they arrive—in short form along the bar and in full if the
user pulls down the status bar to see the notification list.The user can clear the notifications by pulling down the
status bar and hitting the Clear button.
Developers can enhance their applications by using notifications from their applications to inform the user of
important events. For example, an application might want to send a simple notification to the user whenever new
content has been downloaded.A simple notification has a number of important components: ∙ An icon (appears on
status bar and full notification)
∙ Ticker text (appears on status bar)

∙ Notification title text (appears in full notification)

∙ Notification body text (appears in full notification)

∙ An intent (launches if the user clicks on the full notification)

Using the NotificationManager Service

All notifications are created with the help of the NotificationManager.The NotificationManager (within the
android.app package) is a system service that must be requested.The following code demonstrates how to obtain
a valid NotificationManager object using the getSystemService() method:
NotificationManager notifier = (NotificationManager)
getSystemService(Context.NOTIFICATION_SERVICE)

Creating a Simple Text Notification with an Icon

You can set the icon and ticker text, both of which display on the status bar, through the constructor for the
Notification object, as follows:
Notification notify = new Notification(
R.drawable.android_32, "Hello!", System.currentTimeMillis());

Working with the Notification Queue

Now the application is ready to actually notify the user of the event. All that is needed is a call to the notify()
method of the NotificationManager with an identifier and the Notification we configured

Updating Notifications
You don’t want your application’s notifications piling up in the notification bar.Therefore, you might want to
reuse or update notifications to keep the notification list manageable. For example, there is no reason to keep a
notification informing the user that the application is downloading File X when you now want to send another
notification saying File X has finished downloading. Instead, you can simply update the first notification with
new Information
Clearing Notifications
When a user clicks on the notification, the Intent assigned is triggered.At some point after this, the application
might want to clear the notification from the system notifications queue.This is done through a
call to the cancel() method of the NotificationManager object. For instance, the notification we created earlier
could be canceled with the following call: notifier.cancel(NOTIFY_1);

Vibrating the Phone

Vibration is a great way to enable notifications to catch the attention of a user in noisy environments or alert the
user when visible and audible alerts are not appropriate (though a vibrating phone is often noisy on a hard
desktop surface).Android notifications give a fine level of control over how vibration is performed. However,
before the application can use vibration with a notification, an explicit permission is needed.The following XML
within your application’s AndroidManifest.xml file is required to use vibration:
<uses-permission
android:name="android.permission.VIBRATE" />
Without this permission, the vibrate functionality will not work nor will there be any error.With this permission
enabled, the application is free to vibrate the phone however it wants.This is accomplished by describing the
vibrate member variable, which determines the vibration pattern.An array of long values describes the vibration
duration. Thus, the following line of code enabled a simple vibration pattern that occurs whenever the
notification is triggered:
notify.vibrate = new long[] {0, 200, 200, 600, 600};
This vibration pattern vibrates for 200 milliseconds and then stops vibrating for 200 milliseconds. After that, it
vibrates for 600 milliseconds and then stops for that long.To repeat the Notification alert, a notification flag can
be set so it doesn’t stop until the user clears the notification.
notify.flags |= Notification.FLAG_INSISTENT;
An application can use different patterns of vibrations to alert the user to different types of events or even present
counts. For instance, think about a grandfather clock with which you can deduce the time based on the tones that
are played.
Blinking the Lights
Blinking lights are a great way to pass information silently to the user when other forms of alert are not
appropriate.The Android SDK provides reasonable control over a multicolored indicator light, when such a light
is available on the device. Users might recognize this light as a service indicator or battery level warning.An
application can take advantage of this light as well, by changing the blinking rate or color of the light.Warning
Indicator lights are not available on all Android devices. Also, the emulator does not display the light’s state.
This mandates testing on actual hardware. You must set a flag on the Notification object to use the indicator
light.Then, the color of the light must be set and information about how it should blink.The following block of
code configures the indicator light to shine green and blink at rate of 1 second on and 1 second off:
notify.flags |= Notification.FLAG_SHOW_LIGHTS;
notify.ledARGB = Color.GREEN;
notify.ledOnMS = 1000;
notify.ledOffMS = 1000;
Although you can set arbitrary color values, a typical physical implementation of the indicator light has three
small LEDs in red, green, and blue.Although the colors blend reasonably well, they won’t be as accurate as the
colors on the screen. For instance, on the T-Mobile G1, the color white looks a tad pink.

Making Noise
Sometimes, the handset has to make noise to get the user’s attention. Luckily, the Android SDK provides a
means for this using the Notification object. Begin by configuring the audio stream type to use when playing a
sound. Generally, the most useful stream type is STREAM_NOTIFICATION.You can configure the audio stream
type on your notification as follows:
notify.audioStreamType = AudioManager.STREAM_NOTIFICATION;
Now, assign a valid Uri object to the sound member variable and that sound plays when the notification is
triggered.The following code demonstrates how to play a sound that is included as a project resource:
notify.sound = Uri.parse( "android.resource://com.androidbook.simplenotifications/" + R.raw.fallbackring);
Customizing the Notification
Although the default notification behavior in the expanded status bar tray is sufficient for most purposes,
developers can customize how notifications are displayed if they so choose. To do so, developers can use the
RemoteViews object to customize the look and feel of a notification.
The following code demonstrates how to create a RemoteViews object and assign custom text to it:
RemoteViews remote =
new RemoteViews(getPackageName(), R.layout.remote);
remote.setTextViewText(R.id.text1, "Big text here!");
remote.setTextViewText(R.id.text2, "Red text down here!");
notify.contentView = remote;
Designing Useful Notifications
As you can see, the notification capabilities on the Android platform are quite robust—so robust that it is easy to
overdo it and make your application tiresome for the user. Here are some tips for designing useful notifications:
∙ Only use notifications when your application is not in the foreground.When in the foreground, use Toast or
Dialog controls.
∙ Allow the user to determine what types (text, lights, sound, vibration) and frequency of notifications she
will receive, as well as what events to trigger notifications for.
∙ Whenever possible, update and reuse an existing notification instead of creating a new one. ∙

Clear notifications regularly so as not to overwhelm the user with dated information. ∙ When in
doubt, generate “polite” notifications (read: quiet).
∙ Make sure your notifications contain useful information in the ticker, title, and body text fields and launch
sensible intents.
The notification framework is lightweight yet powerful. However, some applications such as alarm clocks or
stock market monitors might also need to implement their own alert windows above and beyond the notification
framework provided. In this case, they may use a background service and launch full Activity windows upon
certain events. In Android 2.0 and later, developers can use the WindowManager.LayoutParams class to enable
activity windows to display, even when the screen is locked with a keyguard.