Lightweight Smart Wearable Audio Application Development

Read the original article：Lightweight Smart Wearable Audio Application Development

Problem Description

Developers of lightweight wearable music applications on HarmonyOS face challenges due to device limitations, API constraints, and complex interactions between the watch and mobile music applications. Key issues include:

• Lack of a consolidated guide for watch-side audio playback and file management.
• Limitations in file naming, playback control, and supported formats.
• Need for background playback, playlist management, and encrypted music handling.
• Interaction with mobile phones for file transfer, playlist queries, and notifications.

The goal is to enable efficient development of music apps while adhering to system constraints and providing seamless user experience.

Background Knowledge

Key concepts and constraints for watch-side music development:

1. Audio Capabilities
   • Play, pause, stop, and query audio playback using JS interfaces (@system.audio).
   • Supports background playback.
   • Only one music app can play at a time.
   • Supports MP3 format only; playback progress cannot be specified.
2. Directory Structure
   • internal://app/music → music files
   • internal://app/folder → playlist files
   • internal://app/music_info → music information files
3. JS Audio Interfaces
   • Properties: src, currentTime, duration, autoplay, loop, volume, muted.
   • Events: onplay, onpause, onstop, onloadeddata, onended, onerror, ontimeupdate.
   • Methods: audio.play(), audio.pause(), audio.stop(), audio.getPlayState()
4. Playlist Management
   • Playlists are text files, using ; to separate songs and , to separate song attributes.
   • Include: file name, type (MP3 = 1), encryption flag, total duration, song name, artist name.
   • Current playlist is indicated in internal://app/cur_playlist.
5. Encrypted Music Handling
   • Developers provide a decryption library (audio_decode.bin) with required interfaces:
     • AUDIO_DecryptFuncion → decrypts music data
     • AUDIO_GetDecryptUnitLength → returns decryption unit size
   • Magic number 0x484d2e62 must be included in the library.
6. File Management
   • Supported via Wear Engine for download, deletion, and query operations.
   • Communication with mobile apps uses message protocols and command words for file transfer, playlist queries, and deletion operations.
   • Maximum file name lengths: music file = 256 bytes, playlist = 32 bytes, song name = 120 bytes, artist = 60 bytes.
7. Error Codes
   • 0 → success
   • 200 → internal error
   • 202 → invalid parameter
   • 300 → I/O exception
   • 301 → file does not exist
   • 302 → path does not exist
   • 303 → failed to copy file
   • 400 → data already sent

Troubleshooting Process

• Ensure package name is added to the system trustlist for JS audio interfaces to work.
• Validate file paths and directories (music, folder, music_info).
• Confirm playlist format and encryption flags are correct.
• Monitor message protocol commands during file transfer and deletion operations.
• Check error codes returned by the music service to diagnose issues.

Analysis Conclusion

• Music service operations rely heavily on trustlist verification, file directory management, and correct message protocol usage.
• Playlist management and decryption libraries must follow strict format and interface requirements.
• Proper handling of background playback and single active music app constraints ensures smooth user experience.

Solution

To successfully develop a music app on HarmonyOS lightweight wearable devices:

1. Follow Directory Conventions
   • Ensure internal://app/music, folder, and music_info directories exist and are used correctly.
2. Use JS Audio Interfaces
   • Implement audio.play(), audio.pause(), audio.stop(), and audio.getPlayState() according to API guidelines.
3. Playlist Management
   • Generate playlists in the correct text format with semicolon and comma separation.
   • Update internal://app/cur_playlist to indicate the active playlist.
4. Encrypted Music
   • Include audio_decode.bin with correct magic number and interface functions.
   • Load only one decryption library at a time due to limited memory.
5. File Management via Wear Engine
   • Configure package name and certificate fingerprint.
   • Use message protocols to download, query, and delete music files or playlists.
   • Handle file transfer completion notifications properly.
6. Error Handling
   • Check error codes from API responses and implement fallback logic where needed.

By following these practices, developers can build robust, efficient, and fully functional music apps for HarmonyOS lightweight wearable devices.

Written by Sinan Yilmaz