Metadata-Version: 2.4
Name: oobss
Version: 0.2.0
Summary: Open online blind source separation toolkit
Author-email: Taishi Nakashima <taishi@ieee.org>
License: oobss Custom Non-Commercial License
        (Apache License 2.0 with Additional Restrictions)
        
        Copyright (c) 2026 oobss contributors
        
        This license is based on the Apache License, Version 2.0 (the "Apache 2.0 License").
        The Apache 2.0 License text appears below and is incorporated by reference.
        
        Additional Restrictions (override Apache 2.0 where applicable)
        ----------------------------------------------------------------
        
        You may use, copy, modify, and distribute this software only under the
        conditions below. If there is any conflict between the Apache 2.0 License and
        these Additional Restrictions, these Additional Restrictions control.
        
        1) Non-Commercial Use Only
           You may not use this software, in whole or in part, for Commercial Purposes.
        
           "Commercial Purposes" means any use intended for or directed toward
           commercial advantage or monetary compensation, including but not limited to:
           - selling software or services that include this software,
           - using this software in paid products, SaaS, or consulting deliverables,
           - internal business operations that generate revenue or reduce commercial
             operating costs as part of a commercial activity.
        
        2) Required Attribution for Any Use
           Any redistribution, publication, deployment, service, product, or research
           artifact that uses this software (including modified versions or derivative
           works) must include a clear and visible attribution notice.
        
           The attribution must include at least:
           - the project name: "oobss"
           - the copyright holder/contributors
           - a reference to this license file
        
           Example attribution:
           "This product uses oobss (Copyright (c) 2026 oobss contributors), licensed
           under the oobss Custom Non-Commercial License (Apache 2.0 with Additional
           Restrictions)."
        
        3) Downstream Notice and Pass-Through
           If you distribute this software or derivative works, you must:
           - keep all copyright, license, and attribution notices,
           - provide a copy of this license,
           - require downstream recipients to comply with the same terms.
        
        4) No Trademark License
           This license does not grant permission to use any project or contributor
           names, marks, or logos except as necessary for the required attribution.
        
        5) Reservation of Rights
           All rights not expressly granted are reserved.
        
        ---------------------------------------------------------------------------
        Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction,
        and distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by
        the copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all
        other entities that control, are controlled by, or are under common
        control with that entity. For the purposes of this definition,
        "control" means (i) the power, direct or indirect, to cause the
        direction or management of such entity, whether by contract or
        otherwise, or (ii) ownership of fifty percent (50%) or more of the
        outstanding shares, or (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity
        exercising permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications,
        including but not limited to software source code, documentation
        source, and configuration files.
        
        "Object" form shall mean any form resulting from mechanical
        transformation or translation of a Source form, including but
        not limited to compiled object code, generated documentation,
        and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or
        Object form, made available under the License, as indicated by a
        copyright notice that is included in or attached to the work
        (an example is provided in the Appendix below).
        
        "Derivative Works" shall mean any work, whether in Source or Object
        form, that is based on (or derived from) the Work and for which the
        editorial revisions, annotations, elaborations, or other modifications
        represent, as a whole, an original work of authorship. For the purposes
        of this License, Derivative Works shall not include works that remain
        separable from, or merely link (or bind by name) to the interfaces of,
        the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including
        the original version of the Work and any modifications or additions
        to that Work or Derivative Works thereof, that is intentionally
        submitted to Licensor for inclusion in the Work by the copyright owner
        or by an individual or Legal Entity authorized to submit on behalf of
        the copyright owner. For the purposes of this definition, "submitted"
        means any form of electronic, verbal, or written communication sent
        to the Licensor or its representatives, including but not limited to
        communication on electronic mailing lists, source code control systems,
        and issue tracking systems that are managed by, or on behalf of, the
        Licensor for the purpose of discussing and improving the Work, but
        excluding communication that is conspicuously marked or otherwise
        designated in writing by the copyright owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity
        on behalf of whom a Contribution has been received by Licensor and
        subsequently incorporated within the Work.
        
        2. Grant of Copyright License.
        Subject to the terms and conditions of this License, each Contributor
        hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
        royalty-free, irrevocable copyright license to reproduce, prepare
        Derivative Works of, publicly display, publicly perform, sublicense,
        and distribute the Work and such Derivative Works in Source or Object
        form.
        
        3. Grant of Patent License.
        Subject to the terms and conditions of this License, each Contributor
        hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
        royalty-free, irrevocable (except as stated in this section) patent
        license to make, have made, use, offer to sell, sell, import, and
        otherwise transfer the Work, where such license applies only to those
        patent claims licensable by such Contributor that are necessarily
        infringed by their Contribution(s) alone or by combination of their
        Contribution(s) with the Work to which such Contribution(s) was
        submitted. If You institute patent litigation against any entity
        (including a cross-claim or counterclaim in a lawsuit) alleging that
        the Work or a Contribution incorporated within the Work constitutes
        direct or contributory patent infringement, then any patent licenses
        granted to You under this License for that Work shall terminate
        as of the date such litigation is filed.
        
        4. Redistribution.
        You may reproduce and distribute copies of the Work or Derivative Works
        thereof in any medium, with or without modifications, and in Source or
        Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or
            Derivative Works a copy of this License; and
        
        (b) You must cause any modified files to carry prominent notices
            stating that You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works
            that You distribute, all copyright, patent, trademark, and
            attribution notices from the Source form of the Work,
            excluding those notices that do not pertain to any part of
            the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its
            distribution, then any Derivative Works that You distribute must
            include a readable copy of the attribution notices contained
            within such NOTICE file, excluding those notices that do not
            pertain to any part of the Derivative Works, in at least one
            of the following places: within a NOTICE text file distributed
            as part of the Derivative Works; within the Source form or
            documentation, if provided along with the Derivative Works; or,
            within a display generated by the Derivative Works, if and
            wherever such third-party notices normally appear. The contents
            of the NOTICE file are for informational purposes only and
            do not modify the License. You may add Your own attribution
            notices within Derivative Works that You distribute, alongside
            or as an addendum to the NOTICE text from the Work, provided
            that such additional attribution notices cannot be construed
            as modifying the License.
        
        You may add Your own copyright statement to Your modifications and
        may provide additional or different license terms and conditions
        for use, reproduction, or distribution of Your modifications, or
        for any such Derivative Works as a whole, provided Your use,
        reproduction, and distribution of the Work otherwise complies with
        the conditions stated in this License and the Additional Restrictions
        above.
        
        5. Submission of Contributions.
        Unless You explicitly state otherwise, any Contribution intentionally
        submitted for inclusion in the Work by You to the Licensor shall be
        under the terms and conditions of this License, without any additional
        terms or conditions. Notwithstanding the above, nothing herein shall
        supersede or modify the terms of any separate license agreement you may
        have executed with Licensor regarding such Contributions.
        
        6. Trademarks.
        This License does not grant permission to use the trade names,
        trademarks, service marks, or product names of the Licensor,
        except as required for reasonable and customary use in describing the
        origin of the Work and reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty.
        Unless required by applicable law or agreed to in writing, Licensor
        provides the Work (and each Contributor provides its Contributions) on an
        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
        express or implied, including, without limitation, any warranties or
        conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
        PARTICULAR PURPOSE. You are solely responsible for determining the
        appropriateness of using or redistributing the Work and assume any
        risks associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability.
        In no event and under no legal theory, whether in tort (including
        negligence), contract, or otherwise, unless required by applicable law
        (such as deliberate and grossly negligent acts) or agreed to in writing,
        shall any Contributor be liable to You for damages, including any direct,
        indirect, special, incidental, or consequential damages of any character
        arising as a result of this License or out of the use or inability to use
        the Work (including but not limited to damages for loss of goodwill,
        work stoppage, computer failure or malfunction, or any and all other
        commercial damages or losses), even if such Contributor has been advised
        of the possibility of such damages.
        
        9. Accepting Warranty or Additional Liability.
        While redistributing the Work or Derivative Works thereof, You may choose
        to offer, and charge a fee for, acceptance of support, warranty,
        indemnity, or other liability obligations and/or rights consistent with
        this License. However, in accepting such obligations, You may act only on
        Your own behalf and on Your sole responsibility, not on behalf of any
        other Contributor, and only if You agree to indemnify, defend, and hold
        each Contributor harmless for any liability incurred by, or claims
        asserted against, such Contributor by reason of your accepting any such
        warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fast-bss-eval>=0.1.4
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=2.2.6; python_version < '3.11'
Requires-Dist: numpy>=2.4.2; python_version >= '3.11'
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.15.3
Requires-Dist: soundfile>=0.12.0
Provides-Extra: docs
Requires-Dist: mkdocs-autorefs>=1.4.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.30.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.16.0; extra == 'docs'
Provides-Extra: realtime
Requires-Dist: torch; extra == 'realtime'
Requires-Dist: torchrir; extra == 'realtime'
Description-Content-Type: text/markdown

# oobss

Open online blind source separation toolkit.

This repository contains classical and online blind source separation algorithms,
plus utilities for configuration, logging, and documentation.

## Installation

Install from PyPI:

```bash
pip install oobss
```

Or with `uv`:

```bash
uv add oobss
```

Install with realtime extras (`torch`, `torchrir`):

```bash
pip install "oobss[realtime]"
```

```bash
uv add "oobss[realtime]"
```

## Development Setup

Create the development environment and run tests:

```bash
uv sync
uv run pytest
```

Run the multi-method comparison example:

```bash
uv run python examples/compare_wav_methods.py \
  examples/data/mixture.wav \
  --methods all \
  --compute-permutation \
  --filter-length 1
```

## Documentation

Build docs locally with Material for MkDocs:

```bash
uv run mkdocs build
```

Preview docs locally:

```bash
uv run mkdocs serve
```

## Example Scripts

- Single WAV + single method CLI:

  ```bash
  uv run python examples/separate_wav_cli.py examples/data/mixture.wav --method batch_auxiva
  ```

- Single WAV + multi-method comparison (optional SI-SDR with references):

  ```bash
  uv run python examples/compare_wav_methods.py \
    examples/data/mixture.wav \
    --methods all \
    --reference-dir examples/data/ref \
    --compute-permutation \
    --filter-length 1 \
    --plot
  ```

  Notes: SI-SDR baseline uses the selected reference-microphone channel
  (`mix[:, ref_mic]`), `--compute-permutation/--no-compute-permutation` can be
  switched for determined/overdetermined evaluation setups, and
  `--filter-length 1` gives SI-SDR-style batch metrics.

- Dataset-wide benchmark with dataloader + aggregation/visualization:

  ```bash
  uv run python examples/benchmark_dataset.py \
    --sample-limit 2 \
    --workers 1 \
    --set dataset.root=/path/to/cmu_arctic_torchrir_dynamic_dataset
  ```

- CMU ARCTIC + torchrir dataset build (torchrir side):

  ```bash
  torchrir-build-dynamic-cmu-arctic \
    --cmu-root /path/to/cmu_arctic \
    --dataset-root outputs/cmu_arctic_torchrir_dynamic_dataset \
    --n-scenes 10 \
    --overwrite-dataset
  ```

  Alternative module form:

  ```bash
  python -m torchrir.datasets.dynamic_cmu_arctic \
    --cmu-root /path/to/cmu_arctic \
    --dataset-root outputs/cmu_arctic_torchrir_dynamic_dataset \
    --n-scenes 10 \
    --overwrite-dataset
  ```

  Optional layout video flags (torchrir):
  `--save-layout-mp4/--no-save-layout-mp4`,
  `--save-layout-mp4-3d/--no-save-layout-mp4-3d`,
  `--layout-video-fps`, `--layout-video-no-audio`.

## Major APIs

For benchmark and multi-method execution, prefer the `oobss.benchmark`
entrypoints (`ExperimentEngine`, `default_method_runner_registry`).
Direct separator classes are lower-level building blocks.

### 1. Batch Separators (`AuxIVA`, `ILRMA`)

Use TF-domain mixtures with shape `(n_frame, n_freq, n_mic)` and run iterative updates.

```python
import numpy as np
from scipy.signal import ShortTimeFFT, get_window

from oobss import AuxIVA

fs = 16000
fft_size = 2048
hop_size = 512
win = get_window("hann", fft_size, fftbins=True)
stft = ShortTimeFFT(win=win, hop=hop_size, fs=fs)

# mixture_time: (n_samples, n_mic)
mixture_time = np.random.randn(fs, 2)
obs = stft.stft(mixture_time.T).transpose(2, 1, 0)  # (n_frame, n_freq, n_mic)

separator = AuxIVA(obs)
separator.run(30)
est_tf = separator.get_estimate()  # (n_frame, n_freq, n_src)
```

Strategy plug-and-play example:

```python
from oobss import AuxIVA
from oobss.separators.strategies import (
    BatchCovarianceStrategy,
    GaussSourceStrategy,
    IP1SpatialStrategy,
)

separator = AuxIVA(
    obs,
    spatial=IP1SpatialStrategy(),
    source=GaussSourceStrategy(),
    covariance=BatchCovarianceStrategy(),
)
separator.run(30)
```

### 2. Online Separators (`OnlineAuxIVA`, `OnlineILRMA`, `OnlineISNMF`)

Use frame-wise streaming with a shared API:

- `process_frame(frame, request=None)`
- `process_stream(stream, frame_axis=-1, request=None)`

```python
import numpy as np

from oobss import OnlineILRMA, StreamRequest

# stream: (n_freq, n_mic, n_frame)
stream = np.random.randn(513, 2, 100) + 1j * np.random.randn(513, 2, 100)

model = OnlineILRMA(
    n_mic=2,
    n_freq=513,
    n_bases=4,
    ref_mic=0,
    beta=1,
    forget=0.99,
    inner_iter=5,
)
out = model.process_stream_tf(
    stream,
    request=StreamRequest(frame_axis=2, reference_mic=0),
)
separated = out.estimate_tf  # (n_freq, n_src, n_frame)
```

### 3. Unified Separator Contract

Use typed requests for batch/stream execution:
- `fit_transform_tf(..., request=BatchRequest(...))`
- `process_stream_tf(..., request=StreamRequest(...))`

```python
from oobss import AuxIVA, BatchRequest

separator = AuxIVA(obs)  # obs: (n_frame, n_freq, n_mic)
output = separator.fit_transform_tf(
    obs,
    n_iter=50,
    request=BatchRequest(reference_mic=0),
)
estimate_tf = output.estimate_tf
```

### 4. Experiment Engine (`oobss.benchmark`)

Run method sweeps, aggregate results, and generate reports.

- `ExperimentEngine`: task planning and execution
- `expand_method_grids`: method-parameter grid expansion
- `generate_experiment_report`: aggregate CSV/JSON/PDF outputs
- `oobss.dataloaders.create_loader`: dataset loader factory (`torchrir_dynamic` built-in)

```bash
uv run python examples/benchmark_dataset.py \
  --sample-limit 2 \
  --workers 1 \
  --grid batch_ilrma.n_basis=2,4 \
  --grid batch_ilrma.n_iter=50,100
```

Programmatic example:

```python
from pathlib import Path

from oobss.benchmark.config_loader import (
    load_common_config_schema,
    load_method_configs,
)
from oobss.benchmark.config_schema import common_config_to_dict
from oobss.benchmark.engine import ExperimentEngine, parse_grid_overrides
from oobss.benchmark.recipe import recipe_from_common_config
from oobss.benchmark.reporting import generate_experiment_report

cfg = load_common_config_schema(
    Path("examples/benchmark/config/common.yaml")
)
methods = load_method_configs(Path("examples/benchmark/config/methods"))
recipe = recipe_from_common_config(common_config_to_dict(cfg))
grid = parse_grid_overrides(["batch_ilrma.n_basis=2,4"])

engine = ExperimentEngine()
artifacts = engine.run(
    recipe=recipe,
    methods=methods,
    output_root=Path("outputs/dataset_benchmark"),
    workers=1,
    overwrite=True,
    save_framewise=True,
    summary_precision=6,
    save_audio=True,
    method_grid=grid,
)
generate_experiment_report(artifacts.results_path, artifacts.run_root / "reports")
```

## License

This project is distributed under the terms in `LICENSE`.
It is based on Apache License 2.0 with additional restrictions, including:

- non-commercial use only
- required attribution for redistribution/deployment/derived use

Refer to `LICENSE` for the complete and binding terms.

## Future Work

The following roadmap is planned for future iterations:

1. Define a stable dataset contract for `oobss` (track-level manifest, required fields, and directory layout).
2. Introduce a recipe system (`recipe.yaml`) to convert arbitrary raw datasets into the `oobss` data contract.
3. Implement recipe execution modules in `oobss` (validation, conversion, manifest generation, and failure reporting).
4. Extend dataset adapters beyond `torchrir_dynamic` and provide ready-to-use recipes for common public datasets.
5. Strengthen validation tooling for converted datasets (schema checks, duration/channel checks, missing-file diagnostics).
6. Standardize benchmark outputs (`results.jsonl`, per-track details, optional frame-wise metrics) and keep plotting optional.
7. Extend CLI commands for end-to-end workflows:
   - recipe validation and conversion
   - benchmark run, summarize, and plotting
8. Add example recipes for multiple dataset structures and keep examples as thin wrappers around library APIs.
9. Add integration tests for recipe conversion and small-scale benchmark runs to prevent regressions.
