## 1. Project Overview & Quickstart (metabrainz/picard)
## File: README.md
# MusicBrainz Picard
[MusicBrainz Picard](https://picard.musicbrainz.org) is a cross-platform (Linux, macOS, Windows) audio tagging application. It is the official [MusicBrainz](https://musicbrainz.org) tagger.
Picard supports the majority of audio file formats, is capable of using audio fingerprints ([AcoustIDs](https://musicbrainz.org/doc/AcoustID)), performing CD lookups and [disc ID](https://musicbrainz.org/doc/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](https://picard.musicbrainz.org/quick-start/) and the [documentation](https://picard-docs.musicbrainz.org/).
## Features
- **Multiple formats:** Picard supports all popular music formats,
including MP3, FLAC, OGG, M4A, WMA, WAV, and more.
- **AcoustID:** Picard uses [AcoustID](https://musicbrainz.org/doc/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](https://musicbrainz.org)
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](https://picard.musicbrainz.org/plugins/) or
[write your own](https://picard-docs.musicbrainz.org/en/latest/extending/plugins.html).
- **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](COPYING.txt)
or later, and is hosted on GitHub where it is actively
developed.
## Installation
Binary downloads are available on the [Picard download page](https://picard.musicbrainz.org/downloads/).
[INSTALL.md has instructions on building this codebase.](INSTALL.md)
## Support and issue reporting
Please report all bugs and feature requests in the [MusicBrainz issue tracker](https://tickets.metabrainz.org/browse/PICARD). If you need support in using Picard please read the [documentation](https://picard-docs.musicbrainz.org/) first and have a look at the [MusicBrainz community forums](https://community.metabrainz.org/c/picard).
## Trivia
Picard is named after [Captain Jean-Luc Picard](https://en.wikipedia.org/wiki/Jean-Luc_Picard) from the TV series [Star Trek: The Next Generation](https://en.wikipedia.org/wiki/Star_Trek:_The_Next_Generation).
---
## File: po/README.md
Translations
============
Picard translations are handled by [Weblate](https://translations.metabrainz.org/projects/picard/). For translation instructions please see [Picard, Picard Website and Picard User Guide Internationalization](https://wiki.musicbrainz.org/MusicBrainz_Picard/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
--------------
* [Weblate Client](https://docs.weblate.org/en/latest/wlc.html)
* [Babel](https://babel.pocoo.org/)
Picard source tree strings
--------------------------
Their translations are handled at
One can update `picard.pot` using:
```bash
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
----------------------------------------------------
Translations for the strings from `org.musicbrainz.Picard.appdata.xml.in` and `org.musicbrainz.Picard.desktop.in` are handled at .
One can update `appstream/picard-appstream.pot` using:
```bash
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
------------------------------
The translations for the Windows installer are inside the JSON files in `installer/i18n/sources`.
Translation in Weblate is done at
Attributes and countries strings
--------------------------------
Their translations are handled at and
`attributes.pot` and `countries.pot` are updated by [musicbrainz-server project](https://github.com/metabrainz/musicbrainz-server), 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](https://translations.metabrainz.org/accounts/profile/#api). The constants can then be updated with the following command:
```bash
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:
```ini
[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
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](https://doc.qt.io/qt-6/rcc.html).
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.
python3 makeqrc.py
3. Create binary of all resources which will be used by Picard.
python3 compile.py
## 2. Official Technical Reference & Guides (metabrainz/picard-docs)
# Documentation for MusicBrainz Picard
This project was created with the intent of developing a comprehensive user manual for [MusicBrainz Picard](https://picard.musicbrainz.org), a full-featured, cross-platform music file tagging system using metadata from [MusicBrainz](https://musicbrainz.org).
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](https://creativecommons.org/publicdomain/zero/1.0).
The project currently produces the on-line documentation in [ReadTheDocs](https://readthedocs.org) format theme using [Sphinx](https://www.sphinx-doc.org/). 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](https://picard-docs.readthedocs.io/).
## Contributing to the Documentation
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](https://tickets.metabrainz.org/issues/?jql=project%20%3D%20PICARD%20AND%20component%20%3D%20Documentation%20AND%20status%20not%20in%20(Cancelled%2C%20Closed)%20ORDER%20BY%20status%20ASC%2C%20resolution%20DESC) under the Picard project (Documentation component). [Pull Requests](https://github.com/metabrainz/picard-docs/pulls) to address outstanding issues are also appreciated. Please see [CONTRIBUTING.md](https://github.com/metabrainz/picard-docs/blob/main/.github/CONTRIBUTING.md) for more information and additional ways to contribute.
## Current Translation Progress