cycsound 0.1.0__cp314-cp314-macosx_15_0_arm64.whl

cycsound/__init__.py

@@ -0,0 +1,33 @@
+"""cycsound - Cython bindings for Csound."""
+
+from cycsound._core import (
+    # Module-level functions
+    initialize,
+    set_opcode_dir,
+    get_version,
+    get_api_version,
+    get_size_of_myflt,
+    # Enums (Python Enum classes)
+    Msg,
+    Color,
+    Mask,
+    # Enums (cpdef enums from Csound API)
+    Status,
+    FileType,
+    # Classes
+    Csound,
+)
+
+__all__ = [
+    "initialize",
+    "set_opcode_dir",
+    "get_version",
+    "get_api_version",
+    "get_size_of_myflt",
+    "Msg",
+    "Color",
+    "Mask",
+    "Status",
+    "FileType",
+    "Csound",
+]

cycsound/__main__.py

@@ -0,0 +1,275 @@
+"""
+cycsound CLI - Command-line interface for Csound operations.
+
+Usage:
+    cycsound play <file.csd>       Play a CSD file
+    cycsound render <file.csd>     Render CSD to audio file
+    cycsound info                  Show Csound version info
+    cycsound check <file.csd>      Validate a CSD file
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from cycsound import Csound, get_version, get_api_version
+
+
+def _setup_quiet(cs):
+    """Configure Csound for quiet operation."""
+    cs.set_message_level(0)  # Suppress all messages first
+    cs.set_option("-d")  # Suppress displays
+    cs.set_option("-m0")  # Minimal messages
+    cs.set_option("-+msg_color=0")  # Disable color codes
+    cs.set_option("-O null")  # Send output info to null
+
+
+def cmd_play(args):
+    """Play a CSD file in real-time."""
+    csd_path = Path(args.file)
+    if not csd_path.exists():
+        print(f"Error: File not found: {csd_path}", file=sys.stderr)
+        return 1
+
+    cs = Csound()
+
+    # Set options
+    cs.set_option("-odac")  # Real-time audio output
+
+    if args.quiet:
+        _setup_quiet(cs)
+
+    if args.input:
+        cs.set_option(f"-iadc:{args.input}")
+
+    if args.output:
+        cs.set_option(f"-odac:{args.output}")
+
+    # Compile and perform
+    result = cs.compile_csd(str(csd_path))
+    if result != 0:
+        print(f"Error: Failed to compile {csd_path}", file=sys.stderr)
+        return 1
+
+    cs.start()
+
+    try:
+        while not cs.perform_ksmps():
+            pass
+    except KeyboardInterrupt:
+        print("\nInterrupted by user")
+
+    cs.cleanup()
+    return 0
+
+
+def cmd_render(args):
+    """Render a CSD file to an audio file."""
+    csd_path = Path(args.file)
+    if not csd_path.exists():
+        print(f"Error: File not found: {csd_path}", file=sys.stderr)
+        return 1
+
+    # Determine output filename
+    if args.output:
+        output_path = args.output
+    else:
+        output_path = csd_path.with_suffix(".wav")
+
+    cs = Csound()
+
+    # Set options
+    cs.set_option(f"-o{output_path}")
+
+    if args.format:
+        cs.set_option(f"--format={args.format}")
+
+    if args.sample_rate:
+        cs.set_option(f"-r{args.sample_rate}")
+
+    if args.ksmps:
+        cs.set_option(f"-k{args.ksmps}")
+
+    if args.quiet:
+        _setup_quiet(cs)
+    else:
+        print(f"Rendering: {csd_path} -> {output_path}")
+
+    # Compile and perform
+    result = cs.compile_csd(str(csd_path))
+    if result != 0:
+        print(f"Error: Failed to compile {csd_path}", file=sys.stderr)
+        return 1
+
+    cs.start()
+
+    try:
+        while not cs.perform_ksmps():
+            pass
+    except KeyboardInterrupt:
+        print("\nInterrupted by user", file=sys.stderr)
+        cs.cleanup()
+        return 1
+
+    cs.cleanup()
+
+    if not args.quiet:
+        print(f"Done: {output_path}")
+
+    return 0
+
+
+def cmd_info(args):
+    """Display Csound version information."""
+    version = get_version()
+    api_version = get_api_version()
+
+    major = version // 1000
+    minor = (version % 1000) // 10
+    patch = version % 10
+
+    print(f"Csound version: {major}.{minor}.{patch} ({version})")
+    print(f"API version: {api_version}")
+
+    if args.verbose:
+        from cycsound import get_size_of_myflt
+        myflt_size = get_size_of_myflt()
+        myflt_type = "double" if myflt_size == 8 else "float"
+        print(f"MYFLT type: {myflt_type} ({myflt_size} bytes)")
+
+    return 0
+
+
+def cmd_check(args):
+    """Validate a CSD file without performing it."""
+    csd_path = Path(args.file)
+    if not csd_path.exists():
+        print(f"Error: File not found: {csd_path}", file=sys.stderr)
+        return 1
+
+    cs = Csound()
+
+    # Syntax check only
+    cs.set_option("--syntax-check-only")
+
+    if args.quiet:
+        _setup_quiet(cs)
+    else:
+        cs.set_option("-d")
+        cs.set_option("-m0")
+
+    result = cs.compile_csd(str(csd_path))
+
+    if result == 0:
+        if not args.quiet:
+            print(f"OK: {csd_path}")
+        return 0
+    else:
+        if not args.quiet:
+            print(f"FAILED: {csd_path}", file=sys.stderr)
+        return 1
+
+
+def cmd_eval(args):
+    """Evaluate Csound orchestra code."""
+    cs = Csound()
+    cs.set_option("-n")  # No audio output
+
+    if args.quiet:
+        _setup_quiet(cs)
+    else:
+        cs.set_option("-d")
+        cs.set_option("-m0")
+
+    # Set up basic header if not provided
+    code = args.code
+    if "sr" not in code and "sr=" not in code:
+        code = "sr = 44100\nksmps = 32\nnchnls = 2\n0dbfs = 1\n" + code
+
+    result = cs.compile_orc(code)
+    if result != 0:
+        print("Error: Failed to compile orchestra code", file=sys.stderr)
+        return 1
+
+    # If code contains return statement, evaluate and print result
+    if "return" in code.lower():
+        try:
+            value = cs.eval_code(code)
+            print(value)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def main(argv=None):
+    """Main entry point for the cycsound CLI."""
+    parser = argparse.ArgumentParser(
+        prog="cycsound",
+        description="Csound CLI powered by cycsound",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  cycsound play myscore.csd           Play a CSD file
+  cycsound render myscore.csd         Render to myscore.wav
+  cycsound render -o out.wav file.csd Render to specific file
+  cycsound check myscore.csd          Validate CSD syntax
+  cycsound info                       Show Csound version
+""",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"cycsound {get_version() // 1000}.{(get_version() % 1000) // 10}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Play command
+    play_parser = subparsers.add_parser("play", help="Play a CSD file in real-time")
+    play_parser.add_argument("file", help="CSD file to play")
+    play_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
+    play_parser.add_argument("-i", "--input", help="Audio input device")
+    play_parser.add_argument("-o", "--output", help="Audio output device")
+    play_parser.set_defaults(func=cmd_play)
+
+    # Render command
+    render_parser = subparsers.add_parser("render", help="Render CSD to audio file")
+    render_parser.add_argument("file", help="CSD file to render")
+    render_parser.add_argument("-o", "--output", help="Output audio file")
+    render_parser.add_argument("-f", "--format", help="Output format (wav, aiff, flac, ogg)")
+    render_parser.add_argument("-r", "--sample-rate", type=int, help="Sample rate override")
+    render_parser.add_argument("-k", "--ksmps", type=int, help="ksmps override")
+    render_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
+    render_parser.set_defaults(func=cmd_render)
+
+    # Info command
+    info_parser = subparsers.add_parser("info", help="Show Csound version info")
+    info_parser.add_argument("-v", "--verbose", action="store_true", help="Show detailed info")
+    info_parser.set_defaults(func=cmd_info)
+
+    # Check command
+    check_parser = subparsers.add_parser("check", help="Validate a CSD file")
+    check_parser.add_argument("file", help="CSD file to validate")
+    check_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
+    check_parser.set_defaults(func=cmd_check)
+
+    # Eval command
+    eval_parser = subparsers.add_parser("eval", help="Evaluate orchestra code")
+    eval_parser.add_argument("code", help="Orchestra code to evaluate")
+    eval_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
+    eval_parser.set_defaults(func=cmd_eval)
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cycsound-0.1.0.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: cycsound
+Version: 0.1.0
+Summary: Cython bindings for the Csound audio synthesis library
+Keywords: audio,csound,cython,music,synthesis,dsp,sound
+Author-Email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Cython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Homepage, https://github.com/shakfu/cycsound
+Project-URL: Repository, https://github.com/shakfu/cycsound
+Project-URL: Issues, https://github.com/shakfu/cycsound/issues
+Project-URL: Changelog, https://github.com/shakfu/cycsound/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cycsound
+
+Cython bindings for the Csound 6.x API.
+
+## Overview
+
+cycsound is a Cython wrapper for the [Csound](https://csound.com/) audio synthesis library, providing Python bindings for the `csound.h` C API. It offers an alternative to the default ctypes-based `ctcsound.py` wrapper included with Csound.
+
+## Features
+
+- **98% API coverage** of the Csound C API (216/219 functions)
+- **Context manager support** for automatic resource cleanup
+- **GIL release** for all blocking operations (enables true multi-threading)
+- **Static linking support** on macOS (standalone wheels without Csound installation)
+- **Platform support**: macOS, Linux, Windows
+- **CLI** for common operations (play, render, check, info, eval)
+
+## Installation
+
+```sh
+pip install cycsound
+```
+
+## Building From Source
+
+Prerequisites:
+
+- Python >= 3.9
+- Csound 6.x installed:
+  - **macOS**: CsoundLib64.framework in `/Library/Frameworks/`
+  - **Linux**: `libcsound64-dev` package
+  - **Windows**: Csound6_x64 in `C:/Program Files/`
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/cycsound.git
+cd cycsound
+
+# Install in development mode
+make sync
+
+# Or install directly
+pip install .
+```
+
+### Building Wheels
+
+```bash
+# Dynamic linking (requires Csound at runtime)
+make wheel
+
+# Static linking - standalone wheel (macOS only)
+make wheel-static
+```
+
+## Command-Line Interface
+
+cycsound includes a CLI for common Csound operations:
+
+```bash
+# Play a CSD file
+cycsound play myscore.csd
+
+# Render to audio file
+cycsound render myscore.csd                    # Creates myscore.wav
+cycsound render -o output.wav myscore.csd      # Specify output file
+cycsound render -f flac -r 48000 myscore.csd   # FLAC format, 48kHz
+
+# Validate CSD syntax
+cycsound check myscore.csd
+
+# Show Csound version info
+cycsound info
+cycsound info -v    # Verbose output
+
+# Get help
+cycsound --help
+cycsound play --help
+```
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `play <file>` | Play CSD file in real-time |
+| `render <file>` | Render CSD to audio file |
+| `check <file>` | Validate CSD syntax |
+| `info` | Show Csound version |
+| `eval <code>` | Evaluate orchestra code |
+
+### Common Options
+
+| Option | Description |
+|--------|-------------|
+| `-q, --quiet` | Suppress output |
+| `-o, --output` | Output file/device |
+| `-h, --help` | Show help |
+
+## Quick Start
+
+```python
+import cycsound
+
+# Using context manager (recommended)
+with cycsound.Csound() as cs:
+    cs.set_option("-odac")  # Real-time audio output
+    cs.set_option("-d")     # Suppress displays
+    cs.compile_orc("""
+sr = 44100
+ksmps = 32
+nchnls = 2
+0dbfs = 1
+
+instr 1
+    asig oscil 0.5, 440
+    outs asig, asig
+endin
+""")
+    cs.read_score("i1 0 2")
+    cs.run()  # Performs entire score
+# cleanup() called automatically on exit
+
+# Or with manual control
+with cycsound.Csound() as cs:
+    cs.compile_csd("myscore.csd")
+    cs.start()
+    while not cs.perform_ksmps():
+        # Process each k-cycle
+        pass
+```
+
+## API Reference
+
+### Module-level Functions
+
+| Function | Description |
+|----------|-------------|
+| `get_version()` | Returns Csound version (e.g., 6180 for 6.18.0) |
+| `get_api_version()` | Returns API version |
+| `get_size_of_myflt()` | Returns size of MYFLT type (4 or 8) |
+| `initialize(flags=0)` | Initialize Csound library (rarely needed) |
+| `set_opcode_dir(path)` | Set opcode directory override |
+
+### Csound Class
+
+Core methods for audio synthesis:
+
+```python
+# Context manager support
+with cycsound.Csound() as cs:
+    # ... use cs ...
+# cleanup() called automatically
+
+# Compilation
+cs.compile_orc(orc_string)      # Compile orchestra code
+cs.compile_csd(filename)        # Compile CSD file
+cs.compile_csd_text(csd_string) # Compile CSD from string
+cs.read_score(score_string)     # Read score events
+
+# Performance
+cs.run()             # Perform entire score (convenience method)
+cs.start()           # Prepare for performance
+cs.perform()         # Perform entire score (blocks)
+cs.perform_ksmps()   # Perform one control period
+cs.perform_buffer()  # Perform one buffer
+cs.stop()            # Stop performance
+cs.cleanup()         # Close audio/MIDI devices
+cs.reset()           # Reset for new performance
+
+# Configuration
+cs.set_option(option)           # Set command-line option
+cs.get_sr() / cs.get_kr()       # Get sample/control rate
+cs.get_ksmps() / cs.get_nchnls() # Get ksmps/channels
+
+# Channels
+cs.set_control_channel(name, value)
+cs.get_control_channel(name)
+cs.set_string_channel(name, value)
+cs.get_string_channel(name)
+```
+
+### Enums
+
+```python
+# Status codes (return values from Csound operations)
+cycsound.Status.SUCCESS        # 0 - Operation succeeded
+cycsound.Status.ERROR          # -1 - General error
+cycsound.Status.INITIALIZATION # -2 - Initialization error
+cycsound.Status.PERFORMANCE    # -3 - Performance error
+cycsound.Status.MEMORY         # -4 - Memory allocation error
+cycsound.Status.SIGNAL         # -5 - Signal received
+
+# File types
+cycsound.FileType.WAVE         # WAV audio
+cycsound.FileType.FLAC         # FLAC audio
+cycsound.FileType.OGG          # OGG Vorbis audio
+cycsound.FileType.UNIFIED_CSD  # Csound CSD file
+cycsound.FileType.STD_MIDI     # Standard MIDI file
+# ... and 60+ more file type constants
+
+# Message types
+cycsound.Msg.DEFAULT   # Standard message
+cycsound.Msg.ERROR     # Error message
+cycsound.Msg.WARNING   # Warning message
+
+# Message colors
+cycsound.Color.FG_RED  # Foreground colors
+cycsound.Color.FG_GREEN
+cycsound.Color.FG_BOLD # Text attributes
+```
+
+## Development
+
+### Setup
+
+```bash
+# Initial setup
+make sync
+
+# Rebuild after code changes
+make build
+
+# Run tests
+make test          # All tests
+make test-cli      # CLI tests only
+```
+
+### Available Make Targets
+
+| Target | Description |
+|--------|-------------|
+| `make` / `make build` | Build/rebuild the extension |
+| `make sync` | Initial environment setup |
+| `make test` | Run test suite |
+| `make wheel` | Build wheel (dynamic linking) |
+| `make wheel-static` | Build standalone wheel (macOS) |
+| `make release` | Build static wheels for all Python versions |
+| `make check` | Check distribution with twine |
+| `make publish` | Publish to PyPI |
+| `make publish-test` | Publish to TestPyPI |
+| `make clean` | Remove build artifacts |
+| `make help` | Show all targets |
+
+### Static Build Requirements (macOS)
+
+For `make wheel-static`, install dependencies via Homebrew:
+
+```bash
+brew install libsndfile flac opus libvorbis libogg mpg123 lame
+```
+
+## Rationale
+
+This project provides an alternative to the default ctypes-based wrapper. [Cython](https://cython.readthedocs.io/) offers several advantages over ctypes:
+
+- Better performance for tight loops
+- Direct C-level access to Csound internals
+- Ability to release the GIL for true multi-threading
+- Static linking for self-contained distribution
+
+For more details, see this [comparison of wrapping approaches](https://stackoverflow.com/questions/1942298/wrapping-a-c-library-in-python-c-cython-or-ctypes).
+
+## Status
+
+- [x] Wrap enough to play arbitrary CSD files
+- [x] Build static variant as wheel (macOS only)
+- [x] 98% coverage of csound.h API (216/219 functions)
+- [x] GIL release for all blocking operations
+- [x] scikit-build-core based build system
+- [x] Context manager support
+- [x] Test suite (36 tests: core API, CLI, channels, threading, enums)
+- [x] CI/CD with cibuildwheel (GitHub Actions)
+- [ ] Complete wrapping of csound.h (remaining: 3 va_list callbacks)
+- [ ] Include plugin support in wheel
+- [ ] Feature parity with ctcsound.py
+
+## Related Projects
+
+- [ctcsound](https://github.com/csound/csound/blob/develop/interfaces/ctcsound.py) - Official ctypes-based Python wrapper
+- [Csound](https://csound.com/) - The Csound audio synthesis system
+
+## License
+
+See [LICENSE](LICENSE) file.

cycsound-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cycsound/__init__.py,sha256=gv-G06_JGVFWbsrlJFx1qnKKTHP3ouDyF6ANHB-woFA,563
+cycsound/__main__.py,sha256=vCwJLxy0YdCZ1hvK3iC70ni9lgVM-fz0W2fdWpWUiGI,7915
+cycsound/_core.cpython-314-darwin.so,sha256=UXpM5y6k7Vvoj3eIa3rREoGltwCzNgyuly_keDXkF4U,5056344
+cycsound-0.1.0.dist-info/METADATA,sha256=jldgYvmxIPBG7w3p9YOhSUuoQ-ehB204UBCMxl2NwRY,9207
+cycsound-0.1.0.dist-info/WHEEL,sha256=vigfwfBy7qR_O1e5CYhYthzx1fo46v39YFrvEex4Qro,114
+cycsound-0.1.0.dist-info/entry_points.txt,sha256=T9IOPIGCM-Bty4Kpy4BFJU_FYBZedKedS_bn_wncu8E,53
+cycsound-0.1.0.dist-info/licenses/LICENSE,sha256=6yxCBxfRa98CF9FfaLkfETHk6f6ufwtvHtvTP5wxSFw,1279
+cycsound-0.1.0.dist-info/RECORD,,

cycsound-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.6
+Root-Is-Purelib: false
+Tag: cp314-cp314-macosx_15_0_arm64
+

cycsound-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cycsound = cycsound.__main__:main
+

cycsound-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+All third-party code included, used, linked-to or wrapped preserves all
+rights specified by its respective license. (see `docs/licenses` folder).
+
+Otherwise, code in this project has the following license:
+
+MIT License
+
+Copyright (c) 2026 Shakeeb Alireza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.