Two-Minute Tutorial 1 Part 1

Enabling Web Developers to Create Android Apps‎ > ‎Get Started with AppLaud‎ > ‎Two Minute Tutorials using AppLaud‎ > ‎

TMT1 P1 Use PhoneGap Media API & jQuery Mobile UI Framework

This Two-Minute Tutorial (TMT1 Part1) shows how to use AppLaud and the PhoneGap Media API to play an audio file, and use jQuery Mobile for a simple UI using buttons and updated text display. It also shows two ways to access the audio file: as a url, and locally (from the device) using the project's /assets folder.

Prerequisites

Installation of the latest MDS AppLaud plugin, see Get Started
Complete of TMT0 or equivalent (create project, edit files, run app on device or AVD)

Prep

MDS AppLaud 1.2 or above
All code provided in complete files as attachments to this page: index.html and main.js
Review PhoneGap Documentation

HTML5 Audio Tag Support and Android

Blogger Brian Hadaway recently wrote a good summary of HTML5 Audio and Android Devices. Try out his very useful Test for HTML5 Audio Support in any desktop or device browser.

1. Create a new project

Create a new project using the project creation wizard. In the first window select:

Use Built-in PhoneGap
Use Built-in jQuery Mobile
Project Contents: Create Project from Specified Source Directory

Use the attached index.html file
Download into empty directory and Browse to its Location

Select Next > to proceed to the next window of the Project Wizard

Example text for the 2nd page of the project creation wizard shown below.

Note: The above image is specific to SDK Tools 13 and lower. This image will be updated soon. Refer to the latest Getting Started Tutorial, Section 3A Android Project Config for SDK Tools 14+ for the latest tools.

Note: For best device coverage, use Min SDK 7. After selecting the highest build target (API Level 13 in the example above), manually change Min SDK Version to 7.

2. Add Audio Control Buttons and Data to index.html using jQuery Mobile

Note: If the project was created using the steps above, the scripts will be inserted into index.html as shown below. As this app uses the PhoneGap APIs, the PhoneGap line must be included (remove commenting shown below to include javascript):


   <!-- <script type="text/javascript" charset="utf-8" src="phonegap-1.3.0.js"></script> -->

The app uses jQuery Mobile to define a jQuery Mobile page (data-role="page") and three buttons (data-role="button") to control the media player with Start, Pause and Stop actions. Two text spans with html id's are added so the total media length and current position can be updated dynamically from javascript. A two-block grid was used to display the data as the spacing of text in a grid provides a nice separation. The content is given an id (id="content-manual"), which will be used in the next tutorial, TMT1 Part 2.

<!DOCTYPE HTML>

<html>

  <head>

    <meta name="viewport" content="width=screen.width; user-scalable=no" />

    <meta http-equiv="Content-type" content="text/html; charset=utf-8">

    <title>Audio Player</title>
    <!-- NOTE: The following 4 lines are inserted by the project wizard -->
      <link rel="stylesheet" href="jquery.mobile/jquery.mobile-1.0.css" type="text/css">
      <script type="text/javascript" src="jquery.mobile/jquery-1.6.4.min"></script>
      <script type="text/javascript" src="jquery.mobile/jquery.mobile-1.0.js"></script>
      <script type="text/javascript" charset="utf-8" src="phonegap-1.3.0.js"></script>

</head>

<body>

 

<div data-role="page" data-theme="a" id="page-home">

    <div data-role="header" data-nobackbtn="true" data-theme="e">

    <h1>Audio Player</h1>

    </div> <!-- /header -->

    

    <div data-role="content" id="content-manual" data-theme="a">

    

        <div data-role="button" id="playaudio" data-theme="e">Play</div>

        <div data-role="button" id="pauseaudio" data-theme="e">Pause</div>

        <div data-role="button" id="stopaudio" data-theme="e">Stop</div>    

    

        <div class="ui-grid-a">

            <div class="ui-block-a"> Current: <span id="audio_position">0 sec</span></div>

            <div class="ui-block-b">Total: <span id=media_dur>0</span> sec</div>

        </div><!-- /grid-a -->



    </div>  <!-- /content-manual -->

</div>  <!-- /page -->

</body>

</html>

For more information on the html markup used above, see the jQuery Mobile documentation.

At this point the app can be run on a device or AVD for a UI sanity check. None of the buttons will work as the javascript functionality has not been implemented yet. The app should appear as below.

3. Add the javascript functionality

Import the file main.js (see attached) into the project's /assets/www directory, or copy its contents into a .js file of any name. The javascript code will provide initialization and the functions for the buttons created with jQuery Mobile html markup.

Add the following line to index.html immediately AFTER all the other javascript file inclusions (substituting your file name if not main.js):

    <script type="text/javascript" charset="utf-8" src="main.js"></script>

To review main.js, start at the bottom where the new style of jQuery Mobile page initialization (page: page-home) waits for the pageinit event before initializing the buttons' functions. jQuery Mobile style of coding is used to easily implement the actions to take when a 'tap' event is delivered for one of the three buttons:

$('#page-home').live('pageinit',function(){

    $("#playaudio").live('tap', function() {
        // Note: two ways to access media file: web and local file
        var src = 'http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3';

        // local (on device): copy file to project's /assets folder:
        // var src = '/android_asset/spittinggames.m4a';

        playAudio(src);
    });

    $("#pauseaudio").live('tap', function() {
        pauseAudio();
    });

    $("#stopaudio").live('tap', function() {
        stopAudio();
    });
});

The implementation of the three functions playAudio, pauseAudio, and stopAudio, is heavily borrowed from the PhoneGap Documentation and will not be reviewed here. Note that it was edited for robustness (e.g. maintain a pause state).

To update the current position in the media as it progresses, we simply provide this callback for use in PhoneGap's media.getCurrentPosition function and call it about every second.

function setAudioPosition(position) {
$("#audio_position").html(position + " sec");
}

Similar code is used to provide the total media length in the html's span, "media_dur".

4. Add an audio file or use a url to provide the media content

The last piece to provide is the audio file to play. As of this writing, the url in the code is a freely accessed mp3 (also borrowed from the PhoneGap Doc). If it is no longer available substitute your own mp3 or m4a url, or use your own file by including it with the steps below.

        // Note: two ways to access media file: web and local file
        var src = 'http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3';

        // local (on device): copy file to project's /assets folder:
        // var src = '/android_asset/spittinggames.m4a';

To include an audio file in your project and have it loaded onto your device:

Copy an mp3 or m4a file into the project's /assets directory
Edit the line var src = '/android_asset/spittinggames.m4a' to reference your file name

About the /assets Directory: By default an Android app project will load the entire contents of /assets onto the device. Files placed here are accessible using /android_asset/<filename>. Larger files result in a longer wait for the app to load and run.

About the Two Ways to Import or Copy Files into a Project:

From Eclipse, use File -> Import or <right-click-on-directory> -> Import, select General -> File System then locate the directory containing the files. Eclipse will automatically update the project meta-data when files are added to a project this way.
From outside Eclipse (i.e. command 'cp', drag/drop or copy/paste), the files will appear in the Project Explorer, but you must do File -> Refresh or <right-click-on-project-name> -> Refresh to update the project meta-data manually.

5. Run the App and hear a Song!

Load the app and test the buttons to hear music! The total and current media lengths should update as shown below. The Current time will stop when paused. Both times reset to zero when stopped.