Pro Java ME MMAPI: Mobile Media API for Java Micro Edition

Description

Mobile Media API is a low-footprint and versatile API that enables you to create multimedia applications in Java-enabled phones. With this API, it is possible to add and control audio-, video-, and image-based media to MIDlets from different sources.

Pro Java ME MMAPI explores this API in great detail. This book explains the APIs architecture and covers how this architecture sits with the Mobile Independent Device Profile (MIDP). The book also shows you how to best use the multimedia capabilities of a Java-enabled phone.

This book includes detailed examples that cover the necessary basics, like audio playback and tone generation, to advanced issues, like synchronized media playback, video capture, and live radio stream. The book incorporates a mobile phone to model these examples, in addition to the Java Wireless Toolkit emulators.

* This is the first all-in-one reference for creating multimedia applications in Java-enabled phones using the MMAPI.
* Covers MMAPI thoroughly.
* Features real-world examples based on an actual phone - including a video blogging case study. Table of Contents
* Introducing Mobile Media API (MMAPI)
* MMAPI Architecture
* Getting Started with MMAPI
* Media Player Lifecycle and Events
* Accessing Media Over the Network
* Creating and Playing Tones Using ToneControl
* Managing MIDI Using MIDIControl, TempoControl, and PitchControl
* Working with Audio and Video
* Case Study: Device Blogging

CONTENTS:

Pro Java ME MMAPI
Mobile Media API for
Java Micro Edition
Vikram Goyal
Pro Java ME MMAPI: Mobile Media API for Java Micro Edition
Copyright © 2006 by Vikram Goyal
All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying, recording, or by any information storage or retrieval
system, without the prior written permission of the copyright owner and the publisher.
ISBN-13: 978-1-59059-639-5
ISBN-10: 1-59059-639-0
Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1
Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence
of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark
owner, with no intention of infringement of the trademark.
Lead Editor: Steve Anglin
Technical Reviewer: Robert Virkus
Editorial Board: Steve Anglin, Ewan Buckingham, Gary Cornell, Jason Gilmore, Jonathan Gennick,
Jonathan Hassell, James Huddleston, Chris Mills, Matthew Moodie, Dominic Shakeshaft, Jim Sumser,
Keir Thomas, Matt Wade
Project Manager: Sofia Marchant
Copy Edit Manager: Nicole LeClerc
Copy Editor: Julie McNamee
Assistant Production Director: Kari Brooks-Copony
Production Editor: Laura Esterman
Compositor and Artist: Kinetic Publishing Services, LLC
Proofreader: Nancy Riddiough
Indexer: Carol Burbo
Cover Designer: Kurt Krames
Manufacturing Director: Tom Debolski
Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor,
New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail orders-ny@springer-sbm.com, or
visit http://www.springeronline.com.
For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA
94710. Phone 510-549-5930, fax 510-549-5939, e-mail info@apress.com, or visit http://www.apress.com.
The information in this book is distributed on an as is basis, without warranty. Although every precaution
has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to
any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly
by the information contained in this work.
The source code for this book is available to readers at http://www.apress.com in the Source Code section.
Contents
About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About the Technical Reviewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
■CHAPTER 1 Introducing Mobile Media API (MMAPI) . . . . . . . . . . . . . . . . . . . . 1
What Is Mobile Media API (MMAPI)? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
MMAPI Features and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
How Do I Get MMAPI?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
How Does MMAPI Fit with MIDP 2.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Who Supports MMAPI?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
■CHAPTER 2 MMAPI Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Understanding Players and DataSources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
DataSource Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Player Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Understanding the Manager Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Creating Player Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Creating Player Instances for MIDI and Tone Sounds . . . . . . . . . . . . 11
Supported Protocols and Content Types . . . . . . . . . . . . . . . . . . . . . . . 11
Understanding Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
The MIDP 2.0 Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Feature Set Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Security Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
■CHAPTER 3 Getting Started with MMAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
A Simple Multimedia Player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Creating a Functional Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Writing the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Improving AudioPlayerCanvas: Caching Player Instances. . . . . . . . . 29
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
vii
■CHAPTER 4 Media Player Lifecycle and Events. . . . . . . . . . . . . . . . . . . . . . . . . 39
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Exploring the Different Player States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
UNREALIZED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
REALIZED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
PREFETCHED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
STARTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CLOSED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Responding to Player Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Understanding the Event Delivery Mechanism . . . . . . . . . . . . . . . . . . 50
Creating an Event Handling Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Handling a Custom Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
■CHAPTER 5 Accessing Media Over the Network . . . . . . . . . . . . . . . . . . . . . . . 59
Understanding Threads in Java ME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Understanding Permissions for Network Access . . . . . . . . . . . . . . . . . . . . . 63
Putting It Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
■CHAPTER 6 Creating and Playing Tones Using ToneControl . . . . . . . . . . . 73
Understanding Synthetic Tones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Understanding Note, Pitch, and Frequency . . . . . . . . . . . . . . . . . . . . . 74
Using a MMAPI Formula to Calculate Note Values . . . . . . . . . . . . . . . 76
Using the playTone() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Using Tone Sequences with ToneControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Defining Tone Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Playing Sequences Using ToneControl and Player . . . . . . . . . . . . . . . 88
Distributing Tone Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
■CHAPTER 7 Managing MIDI Using MIDIControl, TempoControl,
and PitchControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Understanding MIDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Understanding the MIDI Specification . . . . . . . . . . . . . . . . . . . . . . . . . 96
Storing and Distributing MIDI Messages . . . . . . . . . . . . . . . . . . . . . . 101
■CONTENTS viii
Using MIDI in MMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Playing MIDI Without MIDIControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Playing MIDI with MIDIControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
■CHAPTER 8 Working with Audio and Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Querying the Capabilities of Your Device. . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Understanding Media Encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
A Brief Overview of Sampled Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Storing Sampled Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Controlling Sampled Audio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Setting Preset Stop Times with StopTimeControl. . . . . . . . . . . . . . . 134
Gathering Information Using MetaDataControl . . . . . . . . . . . . . . . . . 139
Mixing Sampled Audio, MIDI, and Tones . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Capturing Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Timed Capture and Playback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Controlled Capture and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Saving Captured Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Capturing Audio from Existing Audio . . . . . . . . . . . . . . . . . . . . . . . . . 162
Working with Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Displaying Video. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Positioning Video and Controlling Volume . . . . . . . . . . . . . . . . . . . . . 169
Capturing Video and Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Seeking Video Frames with FramePositioningControl . . . . . . . . . . . 181
Streaming Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
■CHAPTER 9 Case Study: Device Blogging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
About the Companion Web Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
The Finished MIDlet in Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
MIDlet Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Registering with the Device Blog Web Site . . . . . . . . . . . . . . . . . . . . 186
Logging in to Device Blog Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Creating and Posting Blog Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Creating the MIDlet Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
The Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
The View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
The Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
■CONTENTS ix
Creating the MIDlet Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Creating the Model Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Creating the Utility Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Creating the View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Creating the Control Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
On the Server Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
■APPENDIX A Mobile Media API (MMAPI) Reference . . . . . . . . . . . . . . . . . . . . 239
Package javax.microedition.media. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Interface Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Interface Controllable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Class Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Class MediaException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Interface Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Interface PlayerListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Interface TimeBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Package javax.microedition.media.control . . . . . . . . . . . . . . . . . . . . . . . . . 242
Interface FramePositioningControl . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Interface GUIControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Interface MetaDataControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Interface MIDIControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Interface PitchControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Interface RateControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Interface RecordControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Interface StopTimeControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Interface TempoControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Interface ToneControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Interface VideoControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Interface VolumeControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Package javax.microedition.media.protocol . . . . . . . . . . . . . . . . . . . . . . . . 246
Class ContentDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Class DataSource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Interface SourceStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
■CONTENTS x
■APPENDIX B URI Syntax for Media Locators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
■APPENDIX C Advanced Multimedia Supplements - JSR 234 . . . . . . . . . . 251
Introduction to JSR 234 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
GlobalManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Spectator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
MediaProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
JSR 234 Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
■CONTENTS xi