DOCSEARCHbyAlgolia
Submit Docs

ChucK Documentation

repository·main·Indexed 21 days ago

https://github.com/ccrma/chuck

A strongly-timed, concurrent music programming language for real-time sound synthesis and music creation. Features include dynamic control rates, on-the-fly code modification, and specialized unit generators such as GenX for lookup table utilities and LiSa for multi-voice live sampling and real-time recording. Supports macOS, Windows, Linux, and WebAssembly (WASM).

Tokens
4.5K
Snippets
15
Records
24
Agent score
77%

What's inside ChucK

  1. Build ChucK Core in "Vanilla" mode

    main

    If you want to integrate ChucK into a system that already handles its own real-time audio I/O, you can build only the ChucK core (compiler, VM, and synthesis engine) without any platform-specific audio drivers. This is known as "Vanilla" mode.

    cd src/core
make vanilla

  4. Compile ChucK to WebAssembly (WASM)

    main

    To compile ChucK for web environments, you need the Emscripten SDK. Ensure the Emscripten environment variables are active before running the build command.

    # 1. Activate Emscripten environment
source ./emsdk_env.sh

# 2. Build
cd chuck/src
make web

    Output files (webchuck.wasm and webchuck.js) will be located in:

    chuck/src/host-web/webchuck/js

  5. Integrate ChucK as a component in C++ hosts

    main

    ChucK can be incorporated into other software as a library or component. The host-examples directory provides several C++ implementation patterns for different integration needs:

    • Minimal Integration: Use host-1-minimal.cpp to learn how to initialize a ChucK instance and use it to compile and run ChucK code without real-time audio.
    • Real-time Audio Integration: Use host-2-audio.cpp to integrate a ChucK instance into a host that handles real-time audio, allowing ChucK programs to generate sound on the default output device.
    • C++ to ChucK Communication: Use host-3-globals.cpp to implement communication between your C++ host and ChucK code via ChucK global variables.
    • Shred Management: Use host-4-shreds.cpp to perform high-level shred operations from C++, such as adding shreds, removing the last shred, and querying the Virtual Machine (VM) status.
    • Custom API Binding: Use host-5-custom-api.cpp to bind custom C++ classes to the ChucK environment, making them usable within ChucK scripts.

  6. Build ChucK from source on Windows

    main

    To build ChucK on Windows, use Visual Studio (version 2019 or later is recommended). Navigate to the chuck\src\visual-studio directory, open the chuck.sln solution file, and perform a build.

    Navigate to: chuck\src\visual-studio
Open: chuck.sln

  7. Generate a macOS .icns iconset from a PNG

    main

    To create a macOS .icns icon from a single source PNG, you must first generate an .iconset directory containing multiple appropriately sized PNG files, then use the macOS iconutil command to compile them.

    1. Generate the iconset folder: Use the generate-iconset.py script to create a folder containing 10 different dimensions of the icon.
    2. Compile to .icns: Use iconutil to convert the folder into a single .icns file.

    Note: This process requires python3 and the generate-iconset.py script.

    # 1. Create the iconset folder
python3 generate-iconset.py ~/Desktop/chuck.png

# 2. Compile the iconset into a .icns file
iconutil -c icns ~/Desktop/chuck.iconset -o ~/Desktop/chuck.icns

  9. Deploy WebChucK to a website

    main

    WebChucK runs entirely on the client-side within web browsers and does not require a server backend. To deploy it, you must provide access to three specific files: webchuck.wasm, webchuck.js, and webchuck_host.js.

    You can deploy using one of two methods:

    1. CDN Method (Easiest): Reference the files via a CDN URL directly in your index.html. This method handles CORS-related HTTP security restrictions automatically.
    2. Self-Hosted Method: Host the three files on your own web server. This is a self-contained approach that allows you to customize your own webchuck_host.js. You can download the latest versions of these files from https://chuck.stanford.edu/webchuck/src/.

  10. Locate ChucK code examples from 'Introduction to Programming for Digital Artists'

    main

    The sample code and related audio files from the Manning book "Introduction to Programming for Digital Artists" are installed automatically with ChucK. Depending on your operating system, you can find the examples at the following paths:

    • macOS: /Library/ChucK/examples/book/digital-artists/
    • Windows: C:\Program Files\ChucK\examples\book\digital-artists\
    • Linux: /usr/local/share/doc/chuck/examples/book/digital-artists/ (if installed via the procedure in Appendix A).

    If you are using miniAudicle, you can access these examples directly via the GUI:

    1. Go to File > Open Example.
    2. Locate book/digital-artists in the Example Browser.

  11. Build ChucK from source on macOS

    main

    To build the latest version of ChucK on macOS, clone the repository, navigate to the chuck/src directory, and use make. You can build a standard macOS binary or a universal binary that supports both Intel and Apple Silicon.

    # Standard macOS build
cd chuck/src
make mac

# Universal binary (Intel + Apple Silicon)
make mac-ub

  12. Build ChucK host examples

    main

    To build the provided C++ host examples, use the makefile located in the host-examples directory.

    Note on Build Complexity: The complexity of these makefiles arises from supporting real-time audio across various operating systems. If you are integrating ChucK core into a system that already manages real-time audio, your build process can be significantly simpler. For a simplified build reference, use the 'vanilla' makefile located at ../src/core/makefile.

    make