Metadata-Version: 2.4
Name: musicbrainz2notion
Version: 0.5.0
Summary: A tool to sync artists and music databases from MusicBrainz to Notion.
Project-URL: Repository, https://github.com/Kajiih/musicbrainz2notion
Project-URL: Issues, https://github.com/Kajiih/musicbrainz2notion/issues
Author-email: Kajih <itskajih@gmail.com>
License-File: LICENSE
Keywords: api,database,music,musicbrainz,notion,python,tier list
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.12
Requires-Dist: bs4>=0.0.2
Requires-Dist: cyclopts>=2.9.9
Requires-Dist: frosch<=0.1.5
Requires-Dist: kajihs-utils[loguru]>=0.2.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: musicbrainzngs>=0.7.1
Requires-Dist: notion-client>=2.2.1
Requires-Dist: pandas>=2.2.3
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.9.3
Requires-Dist: tomlkit>=0.13.2
Requires-Dist: toolz>=1.0.0
Requires-Dist: tqdm>=4.66.6
Requires-Dist: typed-settings[attrs,cattrs]>=24.5.0
Requires-Dist: yarl>=1.17
Requires-Dist: zstandard>=0.23.0
Description-Content-Type: text/markdown

# 🎶 MusicBrainz2Notion

<!-- TODO: Don't talk about MusicBrainz from the 1st paragraph, explain what it does on a high level and explain what is MusicBrainz -->
<!-- MusicBrainz2Notion is an automated tool that syncs artist and music data to Notion, making it easy to keep your music database up-to-date. By adding artist IDs to a Notion database, the app automatically retrieves and updates data about artists, albums, and songs, providing a centralized place to browse and organize your favorite music.
-->
A tool for syncing artist and music data from MusicBrainz to Notion databases.
Simply add artist [MusicBrainz](https://musicbrainz.org/) IDs in a Notion database, and the app will automatically fetch and update their data, including albums and songs.

<!-- TODO: Explain how it works (read the database, looks at `To update` artists and get the data of Artist, their albums and songs from MusicBrainz, and update the database) -->

<p align="center">
  <img src="media/musicbrainz_black_and_white.png" alt="Logo" width="300">
</p>

## Contents <!-- omit from toc -->

- [📥 Download](#-download)
- [🏃 Getting Started](#-getting-started)
- [➕ Adding artists](#-adding-artists)
- [⚙️ Configuration](#️-configuration)
  - [Configuration file](#configuration-file)
  - [Environment variables](#environment-variables)
  - [Command Line](#command-line)
- [⚠️ Current Limitations](#️-current-limitations)

## 📥 Download

Find the latest release for your OS [here](https://github.com/Kajiih/MusicBrainz2Notion/releases/latest).

## 🏃 Getting Started

1. Duplicate the [Notion template](https://steel-pram-3bf.notion.site/El-Music-Box-2-0-10e20647c8df80368434ea6ac7208981) to your Notion workspace.
   > 💡 Keep note of the url of the duplicated page (`cmd/ctrl + L` to copy to clipboard), you will need it when using the app for the first time.

2. Set up a [Notion integration](https://developers.notion.com/docs/create-a-notion-integration#getting-started):
   - Create the integration and obtain the Notion API key. Don't forget to grant the permissions to the integration for your newly duplicated page.

3. Run the app.
    - You will be prompted for your notion API key and the url of the main page you duplicated.
    - ❗ The first time you run the app, it will download a small part of MusicBrainz dataset so you need around free 10GB in the app's folder. But don't worry, after processing the data, it only take only around 200MB.

4. Discover who is the mystery artist in the template and enjoy your new music database 🎶!

## ➕ Adding artists

First, look up the MusicBrainz IDs (MBIDs) of the artists you want to sync to Notion.

> 💡 [MBIDs](https://musicbrainz.org/doc/MusicBrainz_Identifier) are universal unique identifiers for artists, releases and songs. You can find the MBIDs in the URL of the artist's page: `https://musicbrainz.org/artist/<MBID>` or in the `details` tab of the artist's page (e.g. [here](https://musicbrainz.org/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da/details): `5b11f4ce-a62d-471e-81fc-a69a8278c7da`).

Once you have the artist IDs, create new pages in the [`Artist database`](https://steel-pram-3bf.notion.site/10e20647c8df80ae923cfa8e19d109d4?v=10e20647c8df81a58be0000cbafdcff3&pvs=4) and enter the MBIDs in the `mbid` field.

> 💡 Make sure that the `To update` field is toggled on so that the app knows which artists to sync.

The next time you will run the app, all albums and songs of the artists, as well as all information about the artists themselves will be added to the database 🎉!

## ⚙️ Configuration

Configuration is loaded from three sources, from lowest to highest priority:

 1. Configuration file
 2. Environment variables
 3. Command-line arguments

### Configuration file

Edit the [`settings.toml`](./settings.toml) file to set the database IDs and API keys or personalize your database.

> 💡 When you are prompted for the notion API key and the link of the database, the configuration file is automatically updated.

### Environment variables

Default settings and settings from the configuration file can be overridden by environment variables.
Environment variables can also be read from the `.env` file in the app folder.

You can find more information about available environment variables in the `.env` template and the `--help` command of the command line app.

### Command Line

If you run the app via the command line (after cloning the repo and installing dependencies), you can pass parameters such as the Notion API key, database IDs, or your Fanart.tv API key.

Use the --help command to see all available options:

```bash
musicbrainz2notion --help
```

## ⚠️ Current Limitations

- **Large Databases**: The app isn’t fully optimized for very large databases yet, so the startup may slow down as the number of pages grows.
- **Notion API**: The Notion API can sometimes be unreliable, and not every scenario is covered yet—occasional crashes may occur.
