View on GitHub

apicultor

API.Cultor: Another BigData approach to sound collections

Apicultor: Modular Music Information Retrieval Toolkit

Python 3.8+ License: GPL v3 Type Hints

Apicultor is a modular toolkit for Music Information Retrieval (MIR), sound analysis, and algorithmic composition. It features a flexible plugin architecture that allows you to enable only the components you need, making it suitable for everything from research environments to embedded systems.

✨ Key Features

🚀 Quick Start

Installation

# Install from source
git clone https://github.com/sonidosmutantes/apicultor.git
cd apicultor
pip install -e .

# Or with Poetry
poetry install

Basic Usage

import apicultor

# Initialize with default plugins
plugin_manager = apicultor.initialize()

# Use database plugin to search for sounds
db_plugin = plugin_manager.get_plugin('database')
results = db_plugin.search_sounds("piano", limit=10)

# Use constraints plugin for optimization
constraints_plugin = plugin_manager.get_plugin('constraints')
constrained_values = constraints_plugin.apply_lower_bounds(data)

Configuration

Create apicultor_config.json:

{
  "plugins": {
    "enabled_modules": ["database", "constraints", "machine_learning"],
    "disabled_modules": ["emotion", "state_machine"],
    "plugin_configs": {
      "database": {
        "default_provider": "freesound",
        "freesound_api_key": "${APICULTOR_FREESOUND_API_KEY}"
      }
    }
  }
}

Or use environment variables:

export APICULTOR_ENABLED_MODULES="database,constraints,machine_learning"
export APICULTOR_FREESOUND_API_KEY="your_api_key"

🧩 Available Plugins

Plugin Description Use Cases
database Sound database access (Freesound, RedPanal, local files) Sound retrieval, corpus building
analysis MIR feature extraction and descriptors Audio analysis, feature vectors
machine_learning Clustering, similarity, classification Sound organization, recommendation
emotion Music emotion analysis and generation Affective computing, mood-based selection
segmentation Audio segmentation algorithms Structure analysis, boundary detection
state_machine Markov chain composition and performance Algorithmic composition, live coding
constraints Mathematical optimization utilities Machine learning, signal processing
sonification Data-to-audio conversion Scientific sonification, synthesis
gradients Optimization algorithms Deep learning, parameter tuning

📖 Documentation

🎪 Interactive Demos

🏆 Recognition

🎵 Use Cases

Research & Analysis

# Enable analysis and ML plugins
export APICULTOR_ENABLED_MODULES="analysis,machine_learning,constraints"

# Extract features and cluster sounds
ml_plugin = plugin_manager.get_plugin('machine_learning')
clusters = ml_plugin.cluster_sounds(feature_vectors, n_clusters=5)

Live Performance

# Enable real-time performance plugins  
export APICULTOR_ENABLED_MODULES="database,state_machine,sonification"

# Create Markov chain composition
sm_plugin = plugin_manager.get_plugin('state_machine')
composition = sm_plugin.create_composition(sounds, transitions)

Embedded/IoT

# Minimal setup for embedded systems
export APICULTOR_ENABLED_MODULES="analysis,constraints"

# Lightweight audio analysis
analysis_plugin = plugin_manager.get_plugin('analysis')
features = analysis_plugin.extract_features(audio_data)

🎛️ Hardware Integration

Custom MIDI Controller

Apicultor supports:

🌐 Database Support

🔬 Research Applications

Apicultor has been used in academic research:

🎨 Creative Projects

Performances with Sonidos Mutantes

Compositions

🛠️ Development

Prerequisites

Setup

git clone https://github.com/sonidosmutantes/apicultor.git
cd apicultor
poetry install --with dev

# Run tests
poetry run pytest

# Type checking
poetry run mypy src/

# Code formatting
poetry run black src/ tests/

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass and code is typed
  5. Submit a pull request

See Development Guidelines for detailed information.

📦 Deployment Scenarios

Docker

docker build -t apicultor .
docker run -e APICULTOR_ENABLED_MODULES="database,analysis" apicultor

Raspberry Pi

# Optimized for embedded systems
export APICULTOR_ENABLED_MODULES="analysis,constraints,sonification"
python -m apicultor.cli.run_analysis --input audio.wav

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

👥 Authors

🔗 Links

🌟 Support

If you find Apicultor useful, please:

APICultor born to realize interdisciplinary performances based on sounds from web platforms. The system combines Music Information Retrieval (MIR) analysis, real-time processing, machine learning, and human control to create new forms of musical expression and sound art.

Spanish version: README_es.md

News

2025 - Major Refactor & Modernization

2018

2017

2016

Developers

See Development Guidelines.

License

Free Software shared with GPL v3, see LICENSE.

Cloud Instrument

Using a desktop computer, a Raspberry pi or bela platform.

See cloud_instrument/README.md

Interactive DEMO: Cloud Instrument. Interactive demo retrieving sounds from the Cloud using MIR descriptors and processing them in realtime (using raspicultor aka raspberry pi + apicultor).

UI

Open Stage Control User Interface

Custom MIDI Controller design

Yaeltex custom MIDI controllers

With a SuperCollider synthesizer/effects processor running in a Raspberry pi, plus an external sound card for high fidelity.

Performances

Sonidos Mutantes

Interdisciplinary performances based on sounds of the web platform Redpanal.org

Proofs of concept:

Components

Dependencies

Tested under Linux, Mac OS (>10.11) and Windows 10.

Debian, Ubuntu 15.04 and 16.04 (and .10). And Docker images. Raspian @ Raspberry Pi

See INSTALL.md