How chichichi959595/artist-tracker-for-obsidian works
1. What this repo is
- A Python CLI batch synchronizer that pulls updates from two external sources—Apple iTunes Search API and YouTube Data API—then writes curated markdown files into an Obsidian vault.
- It is not a web app or daemon; the architecture is a run-to-completion job executed by src/main.py.
2. Top-level control flow
- src/main.py is the orchestration entry point.
- It reads command-line flags like music-only / YouTube-only, loads configuration and environment, then runs the relevant sync pipelines.
- The execution model is linear: load config → fetch remote data → reconcile with local state → write markdown → update SQLite.
3. Configuration boundary
- src/config_loader.py reads the JSON config under config/config.json or a custom path.
- src/env_loader.py reads .env, mainly for YOUTUBE_API_KEY.
- Config defines the two tracked entity sets:
- music: artist names and iTunes artist IDs
- youtube: channel names and YouTube channel IDs
- It also defines the Obsidian vault path, output folder, and behavior flags such as country list, minimum year, and Shorts/Live filtering.
4. External service adapters
- src/itunes.py encapsulates calls to the Apple iTunes Search API.
- src/youtube.py encapsulates calls to the YouTube Data API.
- These modules form the outbound integration boundary; the rest of the app should treat them as data providers, not contain API-specific logic.
5. Local persistence layer
- src/database.py manages a SQLite database used as the authoritative local record of already-seen music items.
- The DB prevents duplicate inserts, stores pending/listened state, and supports restoration if Obsidian content is accidentally removed.
- The repository includes scripts/clear_music_db.py as an operational reset tool for this persistence layer.
6. Obsidian output layer
- src/markdown_writer.py is responsible for turning domain records into markdown for Obsidian.
- src/obsidian_sync.py handles the file-level sync semantics against the vault path and output folder.
- The output boundary is concrete:
- Music.md is maintained as a table
- YouTube.md is maintained as a checklist-style append-only log
7. Music-specific domain rules
- src/music_keys.py appears to centralize music identity and normalization logic.
- This is where the repo’s important deduplication rule lives: songs are compared after normalizing names so variants like singles, remasters, or featured suffixes do not create duplicates.
- This module is a key architectural boundary because it separates business identity from raw API metadata.
8. Music data flow
- For each configured artist, the app fetches recent tracks from iTunes, filtered by country and year/limit options.
- New tracks are checked against SQLite before insertion.
- The markdown table in Music.md is then reconciled with the database state:
- rows marked complete in Obsidian are removed from the file and marked listened in SQLite
- pending rows missing from Obsidian can be restored from SQLite if the artist is still configured
9. YouTube data flow
- For each configured channel, the app fetches recent uploads from YouTube.
- Optional filters remove Shorts and/or Live videos based on config.
- The result is appended as unchecked checklist items in YouTube.md.
- Unlike music, the YouTube flow is described as append-oriented and does not rely on the same restore/listened state machine.
10. Storage layout and operational files
- The repository keeps data/ and logs/ directories in-tree with .gitkeep placeholders, indicating local runtime storage and logging are expected.
- config/config.example.json and .env.example provide the bootstrap boundary for local installation.
- This is a local-first tool: the important system-of-records are the SQLite DB and the Obsidian vault files.
11. Runtime and dependency model
- The project explicitly uses only Python standard library modules.
- That affects the architecture: no package manager, no third-party ORM, and no external sync framework.
- The design is therefore modular but lightweight, with direct integration code in the src/ adapters.
12. Test boundaries
- The tests/ directory covers the major subsystems separately:
- database behavior
- iTunes fetch logic
- YouTube fetch logic
- markdown writing
- Obsidian sync
- main orchestration
- This mirrors the architecture: each adapter or workflow is isolated enough to test independently.
13. What an architecture diagram should show
- A central CLI orchestrator feeding two pipelines:
- Music pipeline: iTunes API → normalization/dedup → SQLite → markdown sync → Obsidian vault
- YouTube pipeline: YouTube API → filtering → markdown append → Obsidian vault
- Surrounding the pipelines are shared concerns:
- config/env loading
- logging
- local file system / SQLite persistence
- reset script for maintenance
Main entry points: main.py CLI main · database.py SQLite DB · markdown_writer.py Markdown writer · obsidian_sync.py Vault sync
Components 12
Orchestration
CLI entrypoint and shared runtime setup
- CLI main · Run-to-completion entrypoint that loads config and dispatches sync pipelines
src/main.py - Config loader · Loads JSON configuration for tracked artists, channels, and vault settings
src/config_loader.py - Env loader · Loads environment variables such as the YouTube API key
src/env_loader.py
Music pipeline
Fetch, normalize, deduplicate, and sync music updates
- iTunes API · Apple iTunes Search API client for music fetches
src/itunes.py - Music keys · Normalizes music identity for deduplication and variant matching
src/music_keys.py
YouTube pipeline
Fetch, filter, and append channel uploads
- YouTube API · YouTube Data API client for recent uploads
src/youtube.py
Storage
Local persistence and vault output
- SQLite DB · Local record of seen music items and listened state
src/database.py - Markdown writer · Turns domain records into Obsidian markdown content
src/markdown_writer.py - Vault sync · Reconciles generated content with the Obsidian vault and output files
src/obsidian_sync.py
Operations
Maintenance and bootstrap files
- DB reset · Operational script for clearing the music SQLite database
scripts/clear_music_db.py - Config example · Example JSON config used to initialize local setup
config/config.example.json - Env example · Example environment file for local secrets and API keys
.env.example
Connections 15
- CLI main → Config loader: loads · Reads repository and vault configuration before syncing
- CLI main → Env loader: loads · Loads runtime secrets and API credentials
- Config loader → Config example: guided by · Bootstrap configuration template
- Env loader → Env example: guided by · Bootstrap environment template
- CLI main → iTunes API: music fetch · Invokes iTunes retrieval when music sync is enabled
- CLI main → YouTube API: video fetch · Invokes YouTube retrieval when YouTube sync is enabled
- iTunes API → Music keys: raw tracks · Music results are normalized before deduplication
- Music keys → SQLite DB: dedup state · Normalized identity is checked against local records
- CLI main → SQLite DB: music persistence · Stores new items and updates listened state
- SQLite DB → Markdown writer: records · Provides authoritative music rows for markdown rendering
- CLI main → Markdown writer: render · Generates Obsidian markdown for music output
- Markdown writer → Vault sync: write files · Produces file content for vault reconciliation
- CLI main → Vault sync: sync vault · Applies file-level sync semantics to Obsidian outputs
- YouTube API → Vault sync: append output · Feeds checklist-style additions into the vault sync layer
- CLI main → DB reset: maintenance · Separate operational reset path for the SQLite database