Microchip Compact MP3 Decoder Library User’s Guide 2012 Microchip Technology Inc. DS70688B Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro, PICSTART, PIC32 logo, rfPIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor, MTP, SEEVAL and The Embedded Control Solutions Company are registered trademarks of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. Analog-for-the-Digital Age, Application Maestro, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, dsPICworks, dsSPEAK, ECAN, ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial Programming, ICSP, Mindi, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit, PICtail, REAL ICE, rfLAB, Select Mode, SQI, Serial Quad I/O, Total Endurance, TSHARC, UniWinDriver, WiperLock, ZENA and Z-Scale are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. GestIC and ULPP are registered trademarks of Microchip Technology Germany II GmbH & Co. & KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2012, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. Printed on recycled paper. ISBN: 978-1-62076-676-7 QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 == DS70688B-page 2 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Table of Contents Chapter 1. Introduction 1.1 MP3 Overview ................................................................................................ 9 1.2 Microchip MP3 Implementation ...................................................................... 9 1.3 Microchip Compact MP3 Decoder Features ................................................ 10 Chapter 2. Library Resources 2.1 Resources .................................................................................................... 11 2.2 Resource Usage ........................................................................................... 11 Chapter 3. Application Programming Interface (API) 3.1 PIC32 MP3 Decoder API Functions ............................................................. 13 Appendix A. License Agreement 2012 Microchip Technology Inc. DS70688B-page 3 Microchip Compact MP3 Decoder Library User’s Guide NOTES: DS70688B-page 4 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Preface NOTICE TO CUSTOMERS All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document. Please refer to our web site (www.microchip.com) to obtain the latest documentation available. Documents are identified with a “DS” number. This number is located on the bottom of each page, in front of the page number. The numbering convention for the DS number is “DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of the document. For the most up-to-date information on development tools, see the MPLAB® X IDE online help. Select the Help menu, and then Topics to open a list of available online help files. INTRODUCTION This chapter contains general information that will be useful to know before you use the Microchip Compact MP3 Decoder Library. Items discussed in this Preface include: • • • • • • • • • Document Layout Conventions Used in this Guide Warranty Registration License Agreement Recommended Reading The Microchip Web Site Development Systems Customer Change Notification Service Customer Support Document Revision History DOCUMENT LAYOUT This document describes how to use the Microchip Compact MP3 Decoder Library with the PIC32 family of devices. The document layout is as follows: • Chapter 1. “Introduction” – This chapter provides an overview of the Microchip Compact MP3 Decoder Library. • Chapter 2. “Library Resources” – This chapter describes the resources available for the Microchip Compact MP3 Decoder Library. • Chapter 3. “Application Programming Interface (API)” – This chapter outlines how the API functions provided in the Microchip Compact MP3 Decoder Library can be included in your application software via the Application Programming Interface. 2012 Microchip Technology Inc. DS70688B-page 5 Microchip Compact MP3 Decoder Library User’s Guide CONVENTIONS USED IN THIS GUIDE This manual uses the following documentation conventions: DOCUMENTATION CONVENTIONS Description Italic characters Initial caps Examples Referenced books MPLAB® IDE User’s Guide Emphasized text ...is the only compiler... A window the Output window A dialog the Settings dialog A menu selection select Enable Programmer Quotes A field name in a window or dialog “Save project before build” Underlined, italic text with right angle bracket A menu path File>Save Bold characters A dialog button Click OK A tab Click the Power tab Text in angle brackets < > A key on the keyboard Press <Enter>, <F1> Plain Courier New Sample source code #define START Filenames autoexec.bat File paths c:\mcc18\h Keywords _asm, _endasm, static Command-line options -Opa+, -Opa- Bit values 0, 1 Constants 0xFF, ‘A’ Italic Courier New A variable argument file.o, where file can be any valid filename Square brackets [ ] Optional arguments mcc18 [options] file [options] Curly brackets and pipe character: { | } Choice of mutually exclusive arguments; an OR selection errorlevel {0|1} Ellipses... Replaces repeated text var_name [, var_name...] Represents code supplied by user void main (void) { ... } Notes DS70688B-page 6 Represents A Note presents information that we want to re-emphasize, either to help you avoid a common pitfall or to make you aware of operating differences between some device family members. A Note can be in a box, or when used in a table or figure, it is located at the bottom of the table or figure. Note: This is a standard note box. CAUTION This is a caution note. Note 1: This is a note used in a table. 2012 Microchip Technology Inc. Preface WARRANTY REGISTRATION Please complete the enclosed Warranty Registration Card and mail it promptly. Sending in the Warranty Registration Card entitles you to receive new product updates. Interim software releases are available at the Microchip web site. LICENSE AGREEMENT Supply of this product does not convey a license under the relevant intellectual property of Thomson and/or Fraunhofer Gesellschaft nor imply any right to use this product in any finished end user or ready-to-use final product. An independent license for such use is required. For details, please visit http://www.mp3licensing.com. RECOMMENDED READING This user’s guide describes how to use the Microchip Compact MP3 Decoder Library. The following are available and recommended as supplemental reference resources. PIC32 Family Reference Manual Sections Family Reference Manual sections are available, which explain the operation of the PIC32 device family architecture and peripheral modules. The specifics of each device family are discussed in the individual family’s device data sheet. MPLAB® XC32 C/C++ Compiler User’s Guide (DS51686) This document details the use of Microchip’s MPLAB XC32 Compiler for PIC32 microcontrollers to develop 32-bit applications. MPLAB® X IDE User’s Guide (DS52027) Consult this document for more information pertaining to the installation and implementation of the MPLAB X IDE software. THE MICROCHIP WEB SITE Microchip provides online support via our web site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQs), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives 2012 Microchip Technology Inc. DS70688B-page 7 Microchip Compact MP3 Decoder Library User’s Guide DEVELOPMENT SYSTEMS CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com, click on Customer Change Notification and follow the registration instructions. The Development Systems product group categories are: • Compilers – The latest information on Microchip C compilers and other language tools • Emulators – The latest information on the Microchip in-circuit emulator, MPLAB REAL ICE™ • In-Circuit Debuggers – The latest information on the Microchip in-circuit debugger, MPLAB ICD 3 • MPLAB X IDE – The latest information on Microchip MPLAB X IDE, the Windows® Integrated Development Environment for development systems tools • Programmers – The latest information on Microchip programmers including the PICkit™ 3 development programmer CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • • • • Distributor or Representative Local Sales Office Field Application Engineer (FAE) Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support DOCUMENT REVISION HISTORY Revision A (October 2012) This is the initial released version of this document. Revision B (November 2012) In this revision, the Performance and Resource Consumption for Microchip Compact MP3 Decoder Library table was updated (Table 2-1). DS70688B-page 8 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Chapter 1. Introduction Thank you for purchasing the Microchip Compact MP3 Decoder Library, which can be used with Microchip’s PIC32 family of devices, and provides the ability to decode MP3 audio. 1.1 MP3 OVERVIEW MP3 is a compression format for storing digital audio data. It is an audio codec that has the capability to compress the original audio source with minor loss in sound quality. The higher the compression ratio, the lower the quality. Therefore, there is a balancing act between file size and audio quality. With the right combination, MP3 encoded data can provide very high quality audio. One of the advantages of MP3 audio is that it can be separated into segments. Each segment is independent and may be decoded or played. This feature makes it a very attractive scheme for streaming audio. MP3 encoding uses psychoacoustic principles. This is a catch-all term for the way sound is perceived psychologically and physiologically by humans. The human ear can nominally hear sounds in the range of 20 Hz to 20,000 Hz, although with age the higher frequencies may be inaudible. One of the principles applied in encoding is to limit the high frequency information, especially at low bit rates. The threshold of sound perception varies with frequency. A low level sound at high frequencies may be inaudible or may add little to the musical experience. In some situations, an otherwise clearly audible sound can be masked by another sound of higher intensity. The MP3 encoder evaluates the perceptual experience loss to the listener by analyzing various such phenomena and makes a qualitative judgment based on the chosen compression rate (bit rate). Alternatively, you may choose a Variable Bit Rate (VBR) and the encoder makes a decision on the bit rate for every frame based on the amount of information that is contained. The task of the decoder is to take the compressed data and produce the decompressed audio on a frame-by-frame basis. 1.2 MICROCHIP MP3 IMPLEMENTATION Table 1-1 shows the different audio layers that use the .mp3 file type. The Microchip Compact MP3 Decoder Library implements the MPEG-1, Audio Layer III, which has been approved in the ISO/IEC 11172-3 standard. TABLE 1-1: MP3 DECODER SUPPORT MATRIX Encoding Format Layer I Layer II Layer III MPEG-1 (Fs = 32, 44.1, 48 kHz) No No Yes MPEG-2 (Fs = 16, 22.05, 24 kHz) No No No MPEG-2.5 (Fs = 8, 11.025, 12 kHz) No No No 2012 Microchip Technology Inc. DS70688B-page 9 Microchip Compact MP3 Decoder Library User’s Guide 1.3 MICROCHIP COMPACT MP3 DECODER FEATURES • • • • • Implements MPEG-1, Audio Layer III decoder (ISO/IEC 11172-3) Simple user interface – initialize decoder and pass MP3 data Optimized C callable APIs Assembly optimized implementation for overall performance Supported sampling rates: - 32 kHz - 44.1 kHz - 48 kHz • Supported bit rates (kbps): - 32 - 40 - 48 - 56 - 64 - 80 - 96 - 112 - 128 - 160 - 192 - 224 - 256 - 320 - Variable Bit Rate (VBR) DS70688B-page 10 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Chapter 2. Library Resources This chapter provides information on the available resources for the Microchip Compact MP3 Decoder Library. Topics covered include: • Resources • Resource Usage 2.1 RESOURCES Several resources related to the Microchip Compact MP3 Decoder Library are available from Microchip: • Hex file for the specific hardware resource • Library binary archive (SW320002-1) • Library source (SW320002-2) The Microchip Compact MP3 Decoder Library can be used as a software resource with your hardware, or with many of Microchip's PIC32 family device hardware resources. Due to many hardware resources, and to conserve space, the related installation and demonstration procedures are not listed in this document. To locate the related installation instructions and demonstration files and procedures for your hardware, refer to the main Microchip web page for your specific board. Note: 2.2 If you are accessing the information for the specific hardware resource from microchipDIRECT, click the More Info link to access the main web page for the board. RESOURCE USAGE TABLE 2-1: Peak MIPS PERFORMANCE AND RESOURCE CONSUMPTION FOR MICROCHIP COMPACT MP3 DECODER LIBRARY Code Size (Kbytes) Data Size (Kbytes) ~29 Total 27.1 Note: 2012 Microchip Technology Inc. 45.58 Decoder State (Heap) 10.76 I/O Buffers 12 Stack 5.4 Tested with CD quality 44.1 kHz, 128 kbps encoded data. DS70688B-page 11 Microchip Compact MP3 Decoder Library User’s Guide NOTES: DS70688B-page 12 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Chapter 3. Application Programming Interface (API) This chapter describes the Application Programming Interface (API) to the Microchip Compact MP3 Decoder Library. The prototype declaration of the API functions, the state buffer used, and the buffer sizes for the audio are located in the header file, MP3Decoder.h. 3.1 PIC32 MP3 DECODER API FUNCTIONS This section lists and describes the following three API functions that are available in the Microchip Compact MP3 Decoder Library: • MP3GetStateSize • MP3Initialize • MP3Decode MP3GetStateSize Description This function gets the size of the MP3 state buffer. Based on the return value, the application allocates the required memory for the MP3 Decoder state. If dynamic memory allocation (malloc) is not used, this function need not be called and the MP3 Decoder state buffer shall be statically defined at compile time with the size of the MP3 Decoder state structure. Prototype unsigned short int MP3GetStateSize(void); Arguments None. Return Values Size of MP3 Decoder state structure size. 2012 Microchip Technology Inc. DS70688B-page 13 Microchip Compact MP3 Decoder Library User’s Guide MP3Initialize Description This function initializes the MP3 Decoder state with the default values. Prototype BOOL MP3Initialize ( void *state ); Arguments *state Pointer to the allocated state memory Return Values TRUE/FALSE DS70688B-page 14 2012 Microchip Technology Inc. Application Programming Interface (API) MP3Decode Description This function decodes a frame of MP3 data. Prototype BOOL MP3Decode (void *state, unsigned char *inBuff, unsigned short int inSize, unsigned short int *used, MP3_FORMAT *format, unsigned char *outBuff, unsigned short int *outSize); In the following example, MP3_FORMAT is the following structure: typedef struct { unsigned short int bitRate; unsigned short int sampleRate; unsigned char bitsPerSample; unsigned char channels; } Arguments *state Pointer to the allocated state memory *inBuff Pointer to input buffer that contains the encoded bit stream inSize Number of valid bytes in the input buffer *used Pointer to the number of bytes consumed in the current frame *format Pointer to the channel information structure *outBuffer Pointer to output buffer that contains decoded PCM samples *outsize Pointer to the number of valid bytes in the output buffer Return Values TRUE/FALSE 2012 Microchip Technology Inc. DS70688B-page 15 Microchip Compact MP3 Decoder Library User’s Guide NOTES: DS70688B-page 16 2012 Microchip Technology Inc. MICROCHIP COMPACT MP3 DECODER LIBRARY USER’S GUIDE Appendix A. License Agreement License Agreement Supply of this product does not convey a license under the relevant intellectual property of Thomson and/or Fraunhofer Gesellschaft nor imply any right to use this product in any finished end user or ready-to-use final product. An independent license for such use is required. For details, please visit http://www.mp3licensing.com. 2012 Microchip Technology Inc. DS70688B-page 17 Microchip Compact MP3 Decoder Library User’s Guide NOTES: DS70688B-page 18 2012 Microchip Technology Inc. NOTES: 2012 Microchip Technology Inc. DS70688B-page 19 Worldwide Sales and Service AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2401-1200 Fax: 852-2401-3431 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 India - Pune Tel: 91-20-2566-1512 Fax: 91-20-2566-1513 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Japan - Osaka Tel: 81-66-152-7160 Fax: 81-66-152-9310 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Farmington Hills, MI Tel: 248-538-2250 Fax: 248-538-2260 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 Santa Clara Santa Clara, CA Tel: 408-961-6444 Fax: 408-961-6445 Toronto Mississauga, Ontario, Canada Tel: 905-673-0699 Fax: 905-673-6509 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 China - Hangzhou Tel: 86-571-2819-3187 Fax: 86-571-2819-3189 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 China - Hong Kong SAR Tel: 852-2401-1200 Fax: 852-2401-3431 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 China - Shenzhen Tel: 86-755-8203-2660 Fax: 86-755-8203-1760 Taiwan - Kaohsiung Tel: 886-7-213-7828 Fax: 886-7-330-9305 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 UK - Wokingham Tel: 44-118-921-5869 Fax: 44-118-921-5820 China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 DS70688B-page 20 Japan - Yokohama Tel: 81-45-471- 6166 Fax: 81-45-471-6122 10/26/12 2012 Microchip Technology Inc.