metaudio: Publish and manage audio files



metaudio (which is a contraction of metadata and audio) is a simple way to publish a folder with MP3 and MP4 (MPEG-4) music and audio recordings on a Joomla website. The extension extracts ID3v2.3 and Apple-style metadata from individual files, creates a listing featuring an audio player and showing the most important metadata (e.g. title, artist, album), and lets visitors view (and authenticated logged-in users edit) all other metadata. Supported metadata include title, artist, album, album artist, grouping, year, track and disk number, composer, comment, genre, tempo, encoder, copyright, JPEG or PNG cover art, description and lyrics. Metadata are cached in the database to improve performance and re-read automatically when files are updated either via the extension interface or the file system.


The primary goal of metaudio is to provide a non-commercial Joomla component that offers an intuitive yet versatile user interface to manage metadata of audio recordings. The current version supports viewing as well as editing Apple-style metadata in m4a (MPEG-4 audio) files and ID3v2.3 metadata in mp3 files but future versions will support additional container formats.


  • integrated metaudio Player and bundled SoundManager 2 player
  • view and edit metadata with a simple interface in front-end
  • read and write Apple-style metadata (data in moov.udta.meta.ilst) in MPEG-4 container of m4a (MPEG-4 audio) files
  • read and write ID3 version 2.3 metadata in mp3 files
  • view container (tree) structure and raw data
  • optimize MPEG-4 containers (remove free boxes, rearrange mdat boxes, update stco boxes as necessary)
  • smart data caching in database for optimum performance

Quick start

In order to get started with metaudio, you need to create a front-end menu item for the extension:

  1. Open Menus in the top menu bar and select one of the existing front-end menus.
  2. Click the icon New in the toolbar.
  3. Click on Select in the Menu Item Type line.
  4. From the subtree that appears, select the leaf node Default listing layout, you can find under Metaudio.
  5. Enter a caption for the audio file listing into the text box MenuTitle.
  6. On the right-hand side, type the relative path of an existing folder into the text field for the parameter Source folder. The path is relative to the Joomla root folder. The extension has automatically created a folder with demo audio recordings upon installation, type media/metaudio to create a listing of these files.
  7. Open the panel Parameters (Component) and adjust other parameter values as necessary. You can add a page title for the audio listing by opening Parameters (System) and typing a custom title.

Once the menu item is created to show audio files from the specified folder, you can access the audio listing from the site front-end. You will be able to edit metadata only if you are logged in to the front-end.

Configuration options

metaudio is primarily oriented at the front-end: visitors can listen to audio recordings as well as view file metadata, while users logged in to the site front-end are displayed an additional Edit link, which takes them to a form where they can update metadata. The back-end is intended for configuring global parameters, which can be overridden by the individual metaudio menu items, as well as performing administrative actions.

Back-end toolbar actions

Clean cache

Purges all cached data from the database.

In order to improve performance, metaudio extracts metadata from audio files and stores them in site database. The time a file was last modified is recorded in the table jos_metaudio_file and compared against the last modified time as set in the file system each time the metadata of a file is about to be displayed. When a new file is added to a folder listed by the component, or an existing file is updated either by overwriting the file or changing metadata using the front-end interface, data are re-read into the table jos_metaudio_data. The action Clean cache removes all such temporary data and forces the database to be re-populated by extracting metadata from files when the metaudio component front-end interface is next displayed, as if metaudio would just have been installed.

Before you would clean the database cache, you might consider removing images (e.g. cover images and artist photos) from the Joomla cache. To improve performance, the extension automatically extracts images it finds embedded in audio files into the Joomla cache folder, and returns links to the images extracted to this temporary location. To remove them, click Tools/Clean cache in the menu bar, select com_metaudio and click Delete.


Displays a dialog box to configure global parameters for the component.

When creating a menu item that invokes the component, each of the values set in the dialog can be overridden by specifying a value other that Use global.

Component parameters

Audio player interface

Player interface for the default listing layout. The simple interface uses a compact inline player with play and resume controls and a position indicator, while the advanced interface features additional controls (e.g. seeking to a position within the audio file) and gives richer feedback.

The advanced interface automatically includes the jQuery library it relies on. The simple interface has no external dependencies.

Continue with next Whether to automatically start playing the next sound recording when the current recording finishes playing.
Sort order

Order in which audio files are listed.

Besides the values file name ascending and descending with their obvious behavior, the option as in playlist offers you the ability to supply a playlist file with the extension m3u, which lists the files you would like to have shown as well as their relative order w.r.t. one other. The m3u file should not use paths (neither absolute nor relative). If you have saved your m3u file to the same folder as where your audio files originated from using your favorite music player, you should normally not have any relative or absolute paths within the playlist file.

Download icon Whether to display an icon or link for downloading audio files.
Container structure Whether to show audio file container structure to users logged in to the site. For instance, a hierarchy of MPEG-4 boxes/atoms would be shown for an m4a file, or as-is metadata with minimal transcoding for an mp3 file.
Debug mode Whether the component uses debug mode versions of JavaScript files. Normally, minified script versions are used to save network bandwidth but tracing errors in obfuscated script is a challenging task. The SoundManager 2 code can also provide additional trace information when debug is enabled, in particular it can log status and error messages in the Firebug console.

Access control

[≥ 0.4] Editing audio metadata requires the Edit permission (core.edit), which allows users who have this permission to edit any content in any extension. For a default Joomla installation, users who are members of any of the groups Editor, Publisher, Manager, Administrator and Super Users are granted this permission, while guest users and users members of the groups Registered and Author only do not. If you deny the Edit permission to a user, they will not be able to make changes to audio metadata.

[< 0.4] Editing audio metadata requires the user to be logged in to the website. All registered users can edit metadata. Anonymous (guest) users are permitted to listen to the recordings but they are not allowed to make any changes.

Solutions to selected problems

Garbled characters are shown in the song title of an mp3 file.

The most likely cause is that a wrong character encoding is used in the mp3 file ID3v2 metadata. ID3v2.3 supports character encoding ISO-8859-1 and UTF-16, whereas ID3v2.4 also supports UTF-16BE and UTF-8. Certain music cataloging software, however, uses other character encoding but specifies ISO-8859-1 as the type of encoding used, thereby misleading metaudio and most desktop music management software. If you experience such a problem, you may force a particular character encoding using the drop-down list or text box Character encoding for text data after you click the link Edit on the audio file listing page. When you click Reload, metaudio will transcode all text entries to the specified encoding. Make sure to save the file using the button Save or Apply to make the change permanent.


metaudio is available for download under GNU/GPL.

If you would like to evaluate an upcoming version of the extension, please take a look at the latest build. Installing these unofficial releases on a production site is not recommended.


If you need support to find a solution to a problem you have encountered or you have further questions, please feel free to This email address is being protected from spambots. You need JavaScript enabled to view it.. Our small projects team is glad to give assistance as needed. However, please note that unlike the software itself, which scales with the number of users without putting extra strain on us, e-mail questions take as much time to answer as many there are. Replying to e-mails diverts resources from project development and maintenance, both of which have much higher community value. Therefore, should you want to ask questions, please consider donating to the project first.


It takes time and effort to develop and maintain metaudio. Especially if you use the extension in a commercial environment, you are strongly encouraged to make a donation even though you are not obliged to.

Donate in EUR via PayPal
Donate in USD via PayPal