picard Documentation

1. Project Overview & Quickstart (metabrainz/picard) Copy Chapter

File: README.md Copy Chapter

MusicBrainz Picard

MusicBrainz Picard is a cross-platform (Linux, macOS, Windows) audio tagging application. It is the official MusicBrainz tagger.

Picard supports the majority of audio file formats, is capable of using audio fingerprints (AcoustIDs), performing CD lookups and disc ID submissions, and it has excellent Unicode support. Additionally, there are several plugins available that extend Picard's features.

When tagging files, Picard uses an album-oriented approach. This approach allows it to utilize the MusicBrainz data as effectively as possible and correctly tag your music. For more information, see the illustrated quick start guide to tagging and the documentation.

Features Copy Chapter

• Multiple formats: Picard supports all popular music formats,
  including MP3, FLAC, OGG, M4A, WMA, WAV, and more.
• AcoustID: Picard uses AcoustID
  audio fingerprints, allowing files to be identified by the actual
  music, even if they have no metadata.
• Comprehensive database: Picard uses the open and
  community-maintained MusicBrainz database
  to provide accurate information about millions of music releases.
• CD lookups: Picard can lookup entire music CDs with a click.
• Plugin support: If you need a particular feature, you can choose
  from a selection of available plugins or
  write your own.
• Scripting: A flexible and powerful, yet easy to learn, scripting language
  allows you to exactly specify how your music files will be named and how the
  tags will look like.
• Cover Art: Picard can find and download the correct cover art for your albums.
• Open Source: Picard is licensed under the
  GNU General Public License 2.0
  or later, and is hosted on GitHub where it is actively
  developed.

Installation Copy Chapter

Binary downloads are available on the Picard download page.

INSTALL.md has instructions on building this codebase.

Support and issue reporting Copy Chapter

Please report all bugs and feature requests in the MusicBrainz issue tracker. If you need support in using Picard please read the documentation first and have a look at the MusicBrainz community forums.

Trivia Copy Chapter

Picard is named after Captain Jean-Luc Picard from the TV series Star Trek: The Next Generation.

File: po/README.md Copy Chapter

Translations

Picard translations are handled by Weblate. For translation instructions please see Picard, Picard Website and Picard User Guide Internationalization.

The translation files are automatically synced between the Picard Github repository and Weblate. Translations can be done in Weblate or by updating the translation files directly.

Below is a technical description for managing the translations as a Picard maintainer or developer.

Required tools Copy Chapter

• Weblate Client
• Babel

Picard source tree strings Copy Chapter

Their translations are handled at https://translations.metabrainz.org/projects/picard/app/

One can update picard.pot using:

python setup.py regen_pot_file

Weblate will automatically sync the changed picard.pot and update the translation files (*.po) with msgmerge.

AppStream metadata and XDG desktop file translations Copy Chapter

Translations for the strings from org.musicbrainz.Picard.appdata.xml.in and org.musicbrainz.Picard.desktop.in are handled at https://translations.metabrainz.org/projects/picard/appstream/.

One can update appstream/picard-appstream.pot using:

python setup.py regen_appdata_pot_file

Weblate will automatically sync the changed picard-appstream.pot and update the translation files (appstream/*.po) with msgmerge.

Windows installer translations Copy Chapter

The translations for the Windows installer are inside the JSON files in installer/i18n/sources.
Translation in Weblate is done at https://translations.metabrainz.org/projects/picard/installer/

Attributes and countries strings Copy Chapter

Their translations are handled at https://translations.metabrainz.org/projects/musicbrainz/attributes/ and https://translations.metabrainz.org/projects/musicbrainz/countries/

attributes.pot and countries.pot are updated by musicbrainz-server project, outside the Picard project.

Picard maintainers can regenerate picard/const/attributes.py and picard/const/countries.py, which are using attributes.pot and countries.pot as base. For this an Weblate API key is required, which can be found in your Weblate user settings under API access. The constants can then be updated with the following command:

python setup.py update_constants --weblate-key={YOUR_WEBLATE_API_KEY}

Instead of entering the Weblate API key each time you can also place a file .weblate.ini in the root of the repository with the following content:

[weblate]
url = https://translations.metabrainz.org/api/

[keys]
https://translations.metabrainz.org/api/ = YOUR_WEBLATE_API_KEY

It will retrieve and parse latest attributes.pot and countries.pot to rebuild picard/const/attributes.py and picard/const/countries.py.

File: resources/README.md Copy Chapter

Updating Resources

This directory contains all external resources, like icons, used by Picard.

Picard utilizes the Qt6 Resource Compiler rcc for using these resources in
application. For more information see the documentation.

For adding a new image into existing resources, follow these steps:

1. Add image file (like .png) into resources/images/ and source file (like .svg) into resources/img-src.

2. Generate new .qrc file. This would automatically detect any changes in directory.

   text Copy

   python3 makeqrc.py

3. Create binary of all resources which will be used by Picard.

   text Copy

   python3 compile.py

2. Official Technical Reference & Guides (metabrainz/picard-docs) Copy Chapter

Documentation for MusicBrainz Picard

This project was created with the intent of developing a comprehensive user manual for MusicBrainz Picard, a full-featured, cross-platform music file tagging system using metadata from MusicBrainz.

This documentation project is open source and provided under CC0 1.0. To view a copy of this license, visit https://creativecommons.org/publicdomain/zero/1.0.

The project currently produces the on-line documentation in ReadTheDocs format theme using Sphinx. Stand-alone PDF documents are also being produced. The latest build of the documentation produced by this initiative can be viewed on the web page.

Contributing to the Documentation Copy Chapter

This documentation project only exists because of the volunteer effort that goes into its development.

Further high quality contributions are welcomed from all Picard users wanting to be part of the open source community that creates and maintains this valuable music tool. Even if you cannot write code, based on your experience of using Picard any help you can give to improve this documentation further will be most appreciated - and even if you cannot improve the existing help, if you can create or maintain translations into other languages, that would be of great benefit.

If you notice an error in the documentation or have additional or updated material to contribute, please create a ticket under the Picard project (Documentation component). Pull Requests to address outstanding issues are also appreciated. Please see CONTRIBUTING.md for more information and additional ways to contribute.

Current Translation Progress Copy Chapter