README.md

# osc

*Erlang support for the Open Sound Control protocol*

[![Build Status][gh-actions-badge]][gh-actions]
[![Erlang Versions][erlang-badge]][versions]
[![Tag][github-tag-badge]][github-tag]

[![Project Logo][logo]][logo-large]

This is an implementation of the Open Sound Control (OSC) protocol written
in Erlang with OTP. The project provides the following:

* `osc_lib`: an API for encoding and decoding OSC messages
* `osc_client`: a manageed UDP client for OSC servers
* `osc`: an OTP application (release-baseed) for creeating custom OSC servers

For more information about OSC, see the links below in the 
[Resources](#resources) section.

## Setup

Include one of the following in your project's `rebar.config`: 

``` erlang
%% Latest Release
{deps, [
    {osc, {git, "https://github.com/erlsci/osc", {tag, "2.1.0"}}}
]}.

%% Unstable
{deps, [
    {osc, {git, "https://github.com/erlsci/osc", {branch, "release/2.2.x"}}}
]}.
```

## Encoding / Decoding OSC Messagees

TBD

## Connecting to OSC Servers

The following is a demonstration using the Erlang OSC server, but first we need
to add the default addresses to the server:

``` erlang
1> osc:add_addresses().
```

Now we can create a client connection manager and send a message to the default
address:

``` erlang
2> osc_client:start().
3> {ok, Pid} = osc_client:connect("localhost", 2357).
4> osc_client:cast_msg(Pid, "/debug/log_message").
ok
```

No value is expected from the server, so `cast_msg` is used.

The Erlang OSC server will then log the output:

``` erlang
=INFO REPORT==== 27-Nov-2020::14:02:22.687276 ===
Received message: []
```

Here's an example of connecting to a SuperCollider server:

``` erlang
1> osc_client:start().
2> {ok, Pid} = osc_client:connect("localhost", 57110).
3> osc_client:call_msg(Pid, "/status").
{message,"/status.reply",
         [1,0,0,1,0,0.8447946310043335,8.175622940063477,4.41e4,
          44101.72468382008]}
```

`call_msg` was used here since we expect a value back from the server.

For more example usage, you may be interested in viewing the source for the
LFE project [undertone](https://github.com/lfex/undertone). While written in
LFE, it make extensive use of `osc_client` and might offer the curious coder
significant insights.

## Running Project Tests

    rebar3 as test check

## Running the Default Server

Start an interactive Erlang shell:

    rebar3 shell

Note: that will automatically start all the release dependency applications as
well as `osc` itself.

Then you can use the simple API for adding OSC addresses to the default server:

``` erlang
1> osc:get_addresses().
[]
2> osc:add_addresses().
[ok]
3> osc:get_addresses().
["/debug/log_message"]
4> osc:remove_addresses().
[ok]
5> osc:get_addresses().
[]
```
See the `osc` module for example payloads in adding and removing OSC addresses.


## Using `erlsci/osc` Fork as Custom Server

Update the code in `apps/osc/src/osc.erl` to add the OSC addresses you want to
support (which will require creating the callback code those addreessese will
need). Update `osc_server:init` to call `osc:add_addresses/0` upon startup.

Create and run a release:

    rebar3 release
    cp -r _build/default/rel/osc INSTALL_DIR
    INSTALL_DIR/osc/bin/osc start
    
You can confirm `osc` is running with:

    INSTALL_DIR/osc/bin/osc ping
    
That should return `pong`.

To connect to the running release and get an interactive Erlang shell:

    INSTALL_DIR/osc/bin/osc attach
    Attaching to /tmp/erl_pipes/osc@MM-MAC-7744/erlang.pipe.1 (^D to exit)

    (osc@nodename)1>

## Resources

* [OSC](https://en.wikipedia.org/wiki/Open_Sound_Control) on WikiPedia
* [Intro to OSC](http://opensoundcontrol.org/introduction-osc)
* Open Sound Control's [original home](https://www.cnmat.berkeley.edu/opensoundcontrol)
* [Controlling Ardour with OSC](https://manual.ardour.org/using-control-surfaces/controlling-ardour-with-osc/)
* [SuperCollider OSC Communication](https://doc.sccode.org/Guides/OSC_communication.html)
* [Overtone OSC source code](https://github.com/overtone/overtone/tree/master/src/overtone/osc)
* [OSC 1.0 Specification](http://opensoundcontrol.org/spec-1_0)


[//]: ---Named-Links---

[logo]: priv/images/logo-v2.png
[logo-large]: priv/images/logo-v2-large.png
[github]: https://github.com/erlsci/osc
[gh-actions-badge]: https://github.com/erlsci/osc/workflows/ci%2Fcd/badge.svg
[gh-actions]: https://github.com/erlsci/osc/actions
[erlang-badge]: https://img.shields.io/badge/erlang-19%20to%2023-blue.svg
[versions]: https://github.com/erlsci/osc/blob/master/.github/workflows/cicd.yml
[github-tag]: https://github.com/erlsci/osc/tags
[github-tag-badge]: https://img.shields.io/github/tag/erlsci/osc.svg
[github-downloads]: https://img.shields.io/github/downloads/erlsci/osc/total.svg