Tutorial 1: Transparent Panel (Linear Layout) On MapView (Google Map)
Tutorial 2: “Hit” testing on a View (MapView)

The first challenge to using Google’s Maps in Android is simply informing Eclipse that you’ll need access to Google’s mapping API.  Instead of writing my own tutorial on this, I’ll simply point you to the same well-documented Android v1.5 MapActivity setup that I followed.

The second challenge as always is getting your Map API key to function properly. Google provides full details on installing your Google Map key.  I spent several hours trying to figure out why my API key wasn’t working though…my Google maps always displayed as empty white/gray tiles.  Eventually I tracked the problem down to the fact that Android had created multiple debug.keystore files on my computer.  I’m running Vista so my .keystores were located in both of these directories:

Incorrect: C:\Users\acopernicus\AppData\Local\Android\debug.keystore
Correct: C:\users\<username>\.android\debug.keystore

I wasted time by using the .keystore in my AppData folder as this was the original place where the .keystores were stored in Android v1.0.  However it now seems that Android now uses the .android directory instead.  If you have problems, figure out which directory Eclipse is pulling your .keystore from when signing your apps.
 

At the time of initially writing the streaming tutorial, Android’s media streaming function didn’t work well so I wrote my own.  As of v1.5 however, Android’s MediaPlayer streams very well.  That said, it’s still useful to know how to retrieve a media file from a server and store it on the device.  This would be useful to immediate replay of the file at a later date or for caching files for later playback ‘off the grid’.

Download the source files to get started immediately and then view the rest of the tutorial after the jump.

You may want to look at my old Android v1.0 streaming tutorial for additional details. I don’t want to rewrite that post completely so I’ll mostly focus here on the changes required for Android v1.5. That said, there is very little difference between my old tutorial and this new one.

The most important change is that MediaPlayer.setDataSource() now takes a FileDescriptor instead of a String path to the media File. It seems the reason to use FileDescriptors is for security/permission reasons. In either case though, passing a String path to our media File resulted in errors such as “PVMFErrNotSupported” and “Prepare failed.: status=0×1″. So until I learn otherwise, I recommend using FileDescriptor for the MediaPlayer.


FileInputStream fis = new FileInputStream(mediaFile);
mPlayer.setDataSource(fis.getFD());


The only other change is I can no longer find any File move functionality it Android so I wrote my own. It does exactly what it says, it moves data in one File to a new File location. This is used while streaming the media file so we can double buffer it. The double buffering allows us to simulaneously download to one File while playing from another File. We sync the downloaded data between the Files as more data is downloaded:

public void moveFile(File oldLocation, File newLocation) throws IOException

Download the source files for all the tutorials. The streaming media tutorial available by clicking button #3. Don’t forget to look at my old Android v1.0 streaming tutorial for additional details.

As soon as Google releases the next SDK, we’ll write up more tutorials based on the lessons we’ve learned over the past months.

Until then, we’re getting out to exercise and enjoy some sunshine away from our desks.

Cheers,

Anthony (Biosopher)

Demo video here

I thought I already knew everything about Android’s app lifecycle, but this visual refresher and sample application were a great refresher. Understanding the application lifecycle is crucial to writing good Android apps so this video shoud be useful to pros and newbies alike.

Sleepy Droid says they’ll be creating more videos if the response is positive so visit Sleepy Droid to see if new videos have been posted.

Thanks Sleepy Droid!

Second-gen iPhone: 3G, GPS, only slightly thicker

This is great news for mobile map-based application developers but don’t count on the API being as slick and open as Android’s. Given Apple’s approach so far, they’ll still withhold the vital functionality to get your app really humming.

Why do I say that?

Well for example, Apple’s SDK doesn’t allow applications to run in the background. That means death to any Pocket Journey app that would run on an iPhone as the audio/video would be killed along with your application as soon as someone called. Apple says this is for security reasons, but we know it’s due to Apple’s “control freakish” corporate nature. Happily for us, Android solved this challenge through their Service API.

Seems like Apple wants to step back to the dark ages of the Palm OS which can only handle single-threaded tasks as well

Luckily I was pointed to the solution myself by an experienced Android programmer in Guatemala by the username of cadlg (thanks again!). If you want to see the official Google Android example though, look at Android’s APIDemos’ custom LabelView example.

So here we go. We’ll use the same code as Tutorial 4.1 to keep this simple.

Setting Up Your Custom Class’s XML Resource Files

We’ll only review the code for the TextOnlyButton as it’s identical in concept to the ImageOnlyButton.

First we’ll create a new file in /res/values called attrs.xml

<?xml version=”1.0″ encoding=”utf-8″?>
<resources>

<declare-styleable name=”TextOnlyButton”>

<attr name=”textColorNotFocused” format=”integer”/>
<attr name=”textColorFocused” format=”integer”/>

</declare-styleable>

</resources>

As you see, we first declared a ‘styleable’ with the name of our custom Class. Two attributes were then added to contain the values of our focused & unfocused text colors. By default, attributes have values of String, but in our case, we needed integers to represent the resource id’s we’ll declare in our colors.xml file. You can also declare formats such as “boolean” & others if that suits the requirements of your own project.

Next, we declare values for these custom attributes in our layout’s XML file: tutorial4.xml

<LinearLayout xmlns:android=”http://schemas.android.com/apk/res/android”

xmlns:pj=”http://schemas.android.com/apk/res/com.pocketjourney.tutorials”
android:orientation=”vertical”
android:layout_width=”fill_parent”
android:layout_height=”fill_parent”
android:padding=”10px”>

<com.pocketjourney.view.TextOnlyButton

android:id=”@+id/text_only_button”
android:layout_width=”wrap_content”
android:layout_height=”wrap_content”
android:layout_marginTop=”5px”
style=”?android:attr/buttonStyleSmall”
android:text=”Text Button”
pj:textColorNotFocused=”@drawable/white”
pj:textColorFocused=”@drawable/android_orange”/>

</LinearLayout>

Referring to our new attributes is actually a two step process. First we declared a new namespace (in our case called ‘pj’ as short for PocketJourney) in the parent layout of our custom class:

xmlns:pj=”http://schemas.android.com/apk/res/com.pocketjourney.tutorials”

Next we specified the values of our new attributes in the XML usage of our TextOnlyButton:

pj:textColorNotFocused=”@drawable/white”
pj:textColorFocused=”@drawable/android_orange”

Now you can see why we specified our format=”integer”. Our custom attributes point to the resource id’s of colors specified in our colors.xml file.

Retrieving Custom Attributes During Class Instantiation

Since our Activity has many constructors, we delegate the attribute parsing to an init() method to keep our code clean.

int notFocusedTextColor, focusedTextColor;

private void init(AttributeSet attrs) {

Resources.StyledAttributes a = getContext().obtainStyledAttributes(attrs,R.styleable.TextOnlyButton);
notFocusedTextColor = a.getColor(R.styleable.TextOnlyButton_textColorNotFocused, 0xFF000000);
focusedTextColor = a.getColor(R.styleable.TextOnlyButton_textColorFocused, 0xFF000000);

}

By now you’ve undoubtedly seen the AttributeSet that is always passed into an Activity. Well now you get to use it. First we obtain the StyledAttributes instance by requesting just the StyledAttributes for our custom Class. Next, we call the getColor() and pass two variables: the name of the attribute we want along with a default value in case the user did not specify one.

Take note of our styled attribute’s name as it’s a combination of our custom class’s name and the attribute we specified in the attrs.xml file (e.g. TextOnlyButton_textColorNotFocused).

And That’s It

You can now readily pass your own custom attributes and keep your View variables cleanly enclosed in your XML files. You can download the source to see for yourself. Just look at Tutorial #4.

Prior Tutorials

Tutorial 1: Transparent Panel (Linear Layout) On MapView (Google Map)
Tutorial 2: “Hit” testing on a View (MapView)
Tutorial 3: Custom Media Streaming with MediaPlayer
Tutorial 4.1: Image and Text-Only Buttons

We will create these two new Button extensions as shown:

Step 1: Set Background to ‘null’ in XML or code

The recommended technique is to use the ‘empty’ drawable variable in your ImageButton or TextButton’s XML to set your background to null:

android:background=”@android:drawable/empty”

An optional technique is to extend ImageButton or TextButton and to set the background to null in the constuctor. As above, this is not the recommended approach but may be useful at times:

public YourButtonExtension() {

setBackground(null);

}

And that’s it, only your image or text will display but will have button functionality…except for visually displaying focus. Let’s address that next.

Step 2: Handle onFocus() by overriding onDraw()

We listen for the focus event and update the Button’s text color or button image that way as well. But we’ll do it this way for now.

public void onDraw(Canvas canvas) {

// Since this Button now has no background. We must set the text color to indicate focus.
if (isFocused()) {

// Set the focused text color. In the case of ImageOnlyButton we would .
// instead do setImageResource(imageResourceFocused);
setTextColor(focusedTextColor);

} else {

// Set the non-focused text color. In the case of ImageOnlyButton we would .
// instead do setImageResource(imageResourceNotFocused);
setTextColor(notFocusedTextColor);

}

super.onDraw(canvas);

}

You might be wondering where those text color and image variables come from. We will obtain these focused & not-focused images or text colors from variables passed in from the XML resource file as you’ll see by reading the source code. I won’t go into how that happens here. Instead, I’ll keep this tutorial simple and point you to my next tutorial where I will discuss how to create & pass such custom variables.

And That’s It

You can download the source to see for yourself.

Prior Tutorials

Tutorial 1: Transparent Panel (Linear Layout) On MapView (Google Map)
Tutorial 2: “Hit” testing on a View (MapView)
Tutorial 3: Custom Media Streaming with MediaPlayer

Yes…you read this post’s title correctly. The iPhone SDK lacks the basic mapping API required by applications developers hoping to tie the mobile experience to a geo-specific location (GPS). The only GPS mapping function provided by the iPhone SDK is to send a URL to the iPhone’s built-in Google map application and to let Google handle the rest.

Curiously the iPhone SDK does provide a basic location service API providing the user’s location using cell signal triangulation, but without a map, this information is all-but-useless.

At first glance you might say, “that makes sense as the iPhone doesn’t have GPS built-in because it would have raised the price of an already expensive phone.”

Point taken but all this leaves me to believe that Apple’s take on the iPhone is too media focused and lacks clear understanding of the power provided by location-awareness. That’s great news for the upcoming GPS-enabled Android phones. They’ll have time to widely proliferate before the soon-to-be almost 10M iPhones out there will be replaced with GPS-enabled iPhones.

Imagine if Android had lacked the MapActivity API…?!? From my count, 90% of the most interesting Android Challenge entries would never exist. Without Android’s MapActivity API, we would be left with a few accelerometer-based games and non-SMS messaging apps.

This is great news for Google and perhaps that’s the point. Google wrote the iPhone’s map application and was either not given incentive to make expose its iPhone map through an API or perhaps decided it was smart to keep the iPhone limited in this crucial manner. OK…maybe Apple has a bigger plan as it always does. Maybe Apple is preparing to launch its own mapping application or perhaps AT&T didn’t want Apple to expose such location-based apps because AT&T has its own GPS agenda.

Thoughts anyone?

You’ll be shown screen shots in the video or you can view close ups on our main website

We’ve tried to capture what we view as the power of community and the interest we’ve heard around packaging high quality knowledge from a range of people and making it available through mobile phones.

As you can imagine, there will be a broad range of topics provided through Pocket Journey so it will be a major challenge to filter, pacakge, & deliver just the information you want.

Yes…this GREATLY simplifies the challenge but we wanted to give you a very very “rough” idea of where we’re headed. We plan to provide more details as the project matures.

But don’t just take these static images as the real message. Check out the Pocket Journey video to get a much clearer understanding and to actually “hear” what it’s all about. It will only take 4 minutes of your time.

NOTE: This tutorial was written for Android v1.0.  I have just updated the Android streaming media player tutorial/code to v1.5 (Cupcake) with some additional information on the updated code.  You should read that post as well as this one.

This is a long tutorial, but for those of you that have been struggling with streaming of .mp3 audio to Google’s Android’s MediaPlayer, then I hope this tutorial proves useful as you finalize your entries into Google’s Android Challenge

This tutorial will show how to roll your own streaming audio utility for Android’s MediaPlayer. We will buffer 10 seconds of audio and start playing that audio while the rest of the audio loads in the background. We store the streamed audio locally so you could cache it on device for later use or simply let it be garbage collected.

Here’s the source code for those that just want to jump in. You’ll also notice code for the other tutorials as I didn’t have time to strip them out.

Here are a few screenshots of what we’ll be creating:

Basic Layout

The tutorial consists of just two classes:

Tutorial3: Contains the UI layout and process button clicks
StreamingMediaPlayer: Connects to the server, downloads audio into the buffer, and controls the functionality to ensure the audio continues to play seamlessly.

We’ll assume you know about UI layout using Android’s XML resource files and will instead jump right into the audio streaming code.

Start Your Streaming

Upon clicking the “Start Streaming” button, Tutorial3 creates an instance of StreamingMediaPlayer.

new StreamingMediaPlayer(textStreamed, playButton, streamButton,progressBar);

All UI elements are passed to StreamingMediaPlayer so it can perform UI update itself. In a more robust implementation, StreamingMediaPlayer would fire relevant update events and Tutorial3 would handle the UI updates. For simplicity & cleaner code in this tutorial however, StreamingMediaPlayer will be directly updating the UI.

Tutorial3 then calls StreamingMediaPlayer.startStreaming():

audioStreamer.startStreaming(“http://www.pocketjourney.com/audio.mp3″,1444, 180);

Three variables are passed to startStreaming(): a url for the media to stream (link to an .mp3 file in this tutorial), the length in kilobytes of the media file, and the lenght in seconds of the media file. These last two values will be used when updating the progress bar.

AudioStreamer.startStreaming() creates a new thread for streaming the content so we can immediately return control back to the user interface.

public void startStreaming(final String mediaUrl, long mediaLengthInKb, long mediaLengthInSeconds) throws IOException {

this.mediaLengthInKb = mediaLengthInKb;
this.mediaLengthInSeconds = mediaLengthInSeconds;

Runnable r = new Runnable() {

public void run() {

try {

downloadAudioIncrement(mediaUrl);

} catch (IOException e) {

Log.e(getClass().getName(), “Initialization error for fileUrl=” + mediaUrl, e);
return;

}

}

};
new Thread(r).start();

}

Incremental Media Download

This is where the magic happens as we download media content from the the url stream until we have enough content buffered to start the MediaPlayer. We then let the MediaPlayer play in the background while we download the remaining audio. If the MediaPlayer reaches the end of the buffered audio, then we transfer any newly downloaded audio to the MediaPlayer and let it start playing again.

Things get a little tricky here because:

(a) The MediaPlayer seems to lock the file so we can’t simply append our content to the existing file.
(b) Pausing the MediaPlayer to load the new content takes awhile so we only want to interrupt it when absolutely necessary.
(c) Accessing the MediaPlayer from a separate thread causes it to crash.

So with those caveats in mind, here’s the method that bufferes the media content to a temporary file:

public void downloadAudioIncrement(String mediaUrl) throws IOException {

// First establish connection to the media provider
URLConnection cn = new URL(mediaUrl).openConnection();
cn.connect();
InputStream stream = cn.getInputStream();
if (stream == null) {

Log.e(getClass().getName(), “Unable to create InputStream for mediaUrl:” + mediaUrl);

}

// Create the temporary file for buffering data into
downloadingMediaFile = File.createTempFile(“downloadingMedia”, “.dat”);
FileOutputStream out = new FileOutputStream(downloadingMediaFile);

// Start reading data from the URL stream
byte buf[] = new byte[16384];
int totalBytesRead = 0, incrementalBytesRead = 0;
do {

int numread = stream.read(buf);
if (numread <= 0) {

// Nothing left to read so quit
break;

} else {

out.write(buf, 0, numread);
totalBytesRead += numread;
incrementalBytesRead += numread;
totalKbRead = totalBytesRead/1000;

// Test whether we need to transfer buffered data to the MediaPlayer
testMediaBuffer();

// Update the status for ProgressBar and TextFields
fireDataLoadUpdate();

}

} while (true);

// Lastly transfer fully loaded audio to the MediaPlayer and close the InputStream
fireDataFullyLoaded();
stream.close();

}

What’s up with testMediaBuffer()?

So if you were paying attention, an important piece of functionality must reside in the testMediaBuffer() method. You’re right. That’s the method where we determine whether we need to transfer buffered data to the MediaPlayer because we have enough to start the MediaPlayer or because the MediaPlayer has already played out its previous buffer content.

Before we jump into that, please take note that interacting with a MediaPlayer on non-main UI thread can cause crashes so we always ensure we are interacting with the UI on the main-UI Thread by using a Handler when necessary. For example, we must do so in the following method because it is being called by the media streaming Thread.

private void testMediaBuffer() {

// We’ll place our following code into a Runnable so the Handler can call it for running
// on the main UI thread
Runnable updater = new Runnable() {

public void run() {

if (mediaPlayer == null) {

// The MediaPlayer has not yet been created so see if we have
// the minimum buffered data yet.
// For our purposes, we take the minimum buffered requirement to be:
// INTIAL_KB_BUFFER = 96*10/8;//assume 96kbps*10secs/8bits per byte
if ( totalKbRead >= INTIAL_KB_BUFFER) {

try {

// We have enough buffered content so start the MediaPlayer
startMediaPlayer(bufferedFile);

} catch (Exception e) {

Log.e(getClass().getName(), “Error copying buffered conent.”, e);

}

}

} else if ( mediaPlayer.getDuration() – mediaPlayer.getCurrentPosition() <= 1000 ){

// The MediaPlayer has been started and has reached the end of its buffered
// content. We test for < 1second of data (i.e. 1000ms) because the media
// player will often stop when there are still a few milliseconds of data left to play
transferBufferToMediaPlayer();

}

}

};
handler.post(updater);

}

Starting the MediaPlayer with Initial Content Buffer

Starting the MediaPlayer is very straightforward now. We simply copy all the currently buffered content
into a new Ffile and start the MediaPlayer with it.

private void startMediaPlayer(File bufferedFile) {

try {

File bufferedFile = File.createTempFile(“playingMedia”, “.dat”);
FileUtils.copyFile(downloadingMediaFile,bufferedFile);} catch (IOException e) {

mediaPlayer = new MediaPlayer();
mediaPlayer.setDataSource(bufferedFile.getAbsolutePath());
mediaPlayer.prepare();
fireDataPreloadComplete();

Log.e(getClass().getName(), “Error initializing the MediaPlaer.”, e);
return;

}

}

Transferring Buffered Content to a MediaPlayer That is Already Playing

This is a little trickier but not much. We simply pause the MediaPlayer if it was playing (i.e. the user had not pressed pause), copy over the currently downloaded media content (which may be all of it by now) and then restart the MediaPlayer if it was previously running or had hit the end of its buffer due to a slow network.

private void transferBufferToMediaPlayer() {

try {

// Determine if we need to restart the player after transferring data (e.g. perhaps the user
// pressed pause) & also store the current audio position so we can reset it later.
boolean wasPlaying = mediaPlayer.isPlaying();
int curPosition = mediaPlayer.getCurrentPosition();
mediaPlayer.pause();

// Copy the current buffer file as we can’t download content into the same file that
// the MediaPlayer is reading from.
File bufferedFile = File.createTempFile(“playingMedia”, “.dat”);
FileUtils.copyFile(downloadingMediaFile,bufferedFile);

// Create a new MediaPlayer. We’ve tried reusing them but that seems to result in
// more system crashes than simply creating new ones.
mediaPlayer = new MediaPlayer();
mediaPlayer.setDataSource(bufferedFile.getAbsolutePath());
mediaPlayer.prepare();
mediaPlayer.seekTo(curPosition);

// Restart if at end of prior beuffered content or mediaPlayer was previously playing.
// NOTE: We test for < 1second of data because the media player can stop when there is still
// a few milliseconds of data left to play
boolean atEndOfFile = mediaPlayer.getDuration() – mediaPlayer.getCurrentPosition() <= 1000;
if (wasPlaying || atEndOfFile){

mediaPlayer.start();

}

}catch (Exception e) {

Log.e(getClass().getName(), “Error updating to newly loaded content.”, e);

}

}

Conclusion

To get the real feel for how your audio will download, make sure to set it to a slower network speed. I recommend setting to AT&T’s EDGE network setting as it should give a lower limit on expected performance. You can make these setting’s easy in Eclipse by setting going into your Run or Debug setting’s dialog and making these selections.

Well that’s it. I’ve inluded additional code for handling the ProgressBar and TextField updates but that should all be sufficiently easy to understand once you understand the rest of the code. Good luck during the next week as you finish your Android Challenge submissions.

And of course, here’s the source code. Please post a comment below if I need to explain anything in more detail. You’ll also notice code for the other tutorials as I didn’t have time to strip them out.

Other Tutorials

Tutorial 1: Transparent Panel (Linear Layout) On MapView (Google Map)
Tutorial 2: “Hit” testing on a View (MapView)
Tutorial 4.1: Image and Text-Only Buttons