redact-composer-core 0.2.0

Core components of redact-composer.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245

# ![icon] RedACT Composer

[![docs-badge]][docs-link]
[![crates.io-badge]][crates.io-link]
[![ci-badge]][ci-link]
![license-badge]

**A Rust library for building modular musical composers.**

Composers are built by creating a set of composition elements, and defining how each of these elements will generate
further sub-elements. In this library's domain, these correspond to the
[`Element`](crate::Element) and [`Renderer`](crate::Renderer) traits respectively.

> This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Most importantly at this time
> would be [spec item #4](https://semver.org/spec/v2.0.0.html#spec-item-4).

<hr />
<div align="center">

Jump to: [
[Setup](#setup)
| [Example](#example)
| [Bigger Example](#much-bigger-example)
| [Inspector](#inspector)
| [Feature Flags](#feature-flags)
]
</div>
<hr />

<details open>
<summary>

## Setup
</summary>

```shell
cargo add redact-composer
```

If using the `serde` [feature](#feature-flags), `typetag` is also required:
```shell
cargo add typetag
```
</details>

<details open>
<summary> 

## Example
</summary>

The basic capabilities can be demonstrated by creating a simple I-IV-V-I chord composer. The full code example is
located at
[`redact-composer/examples/simple.rs`](https://github.com/dousto/redact-composer/blob/main/redact-composer/examples/simple.rs).

### Building Blocks
This example composer will use some library-provided elements ([`Chord`](crate::musical::elements::Chord),
[`Part`](crate::elements::Part), [`PlayNote`](crate::elements::PlayNote)) and two new elements:
```rust
#[derive(Element, Serialize, Deserialize, Debug)]
pub struct CompositionRoot;

#[derive(Element, Serialize, Deserialize, Debug)]
struct PlayChords;
```

Before moving ahead, some background: A composition is an n-ary tree structure and is "composed" by starting with a
root [`Element`](crate::Element), and calling its associated [`Renderer`](crate::Renderer) which
generates additional [`Element`](crate::Element)s as children. These children then have their
[`Renderer`](crate::Renderer)s called, and this process continues until tree leaves are reached (i.e. elements that do
not generate further children).

This composer will use the `CompositionRoot` element as a root. Defining a [`Renderer`](crate::Renderer) for this
then looks like:

```rust
struct CompositionRenderer;
impl Renderer for CompositionRenderer {
    type Element = CompositionRoot;

    fn render(
        &self, composition: SegmentRef<CompositionRoot>, context: CompositionContext,
    ) -> Result<Vec<Segment>> {
        let chords: [Chord; 4] = [
            (C, maj).into(),
            (F, maj).into(),
            (G, maj).into(),
            (C, maj).into(),
        ];

        Ok(
            // Repeat the four chords over the composition -- one every two beats
            Rhythm::from([2 * context.beat_length()])
                .iter_over(composition.timing)
                .zip(chords.into_iter().cycle())
                .map(|(subdivision, chord)| chord.over(subdivision.timing()))
                .chain([
                    // Also include the new component, spanning the whole composition
                    Part::instrument(PlayChords).over(composition.timing),
                ])
                .collect(),
        )
    }
}
```

> Note: [`Part::instrument(...)`](crate::elements::Part::instrument) is just a wrapper for another element, indicating
> that notes generated within the wrapped element are to be played by a single instrument at a time.

This [`Renderer`](crate::Renderer) takes a `CompositionRoot` element (via a [`SegmentRef`](crate::SegmentRef)) and generates several
children including [`Chord`](crate::musical::elements::Chord) elements (with a [`Rhythm`](crate::musical::rhythm::Rhythm) of one every two beats over the composition), and
newly defined `PlayChords` element. These children are returned as [`Segment`](crate::Segment)s, which defines where they
are located in the composition's timeline.

At this stage, the [`Chord`](crate::musical::elements::Chord) and `PlayChords` elements are just abstract concepts
however, and need to produce something concrete. This is done with another [`Renderer`](crate::Renderer) for
`PlayChords`:

```rust
struct PlayChordsRenderer;
impl Renderer for PlayChordsRenderer {
    type Element = PlayChords;

    fn render(
        &self, play_chords: SegmentRef<PlayChords>, context: CompositionContext,
    ) -> Result<Vec<Segment>> {
        // `CompositionContext` enables finding previously rendered elements
        let chord_segments = context.find::<Chord>()
            .with_timing(Within, play_chords.timing)
            .require_all()?;
        // As well as random number generation
        let mut rng = context.rng();

        // Map Chord notes to PlayNote elements, forming a triad
        let notes = chord_segments
            .iter()
            .flat_map(|chord| {
                chord.element
                    .iter_notes_in_range(Note::from((C, 4))..Note::from((C, 5)))
                    .map(|note|
                        // Add subtle nuance striking the notes with different velocities
                        note.play(rng.gen_range(80..110) /* velocity */)
                            .over(chord.timing))
                    .collect::<Vec<_>>()
            })
            .collect();

        Ok(notes)
    }
}
```

Here, [`CompositionContext`](crate::render::context::CompositionContext) is used to reference the previously created
[`Chord`](crate::musical::elements::Chord) segments. Then the [`Note`](crate::musical::elements::Note)s from each
[`Chord`](crate::musical::elements::Chord) within an octave range are [`play`](crate::musical::Note::play)ed over the
[`Chord`](crate::musical::elements::Chord) segment's timing.

### Creating the Composer
In essence, a [`Composer`](crate::Composer) is just a set of [`Renderer`](crate::Renderer)s, and can be constructed with
just a little bit of glue:

```rust
let composer = Composer::from(
    RenderEngine::new() + CompositionRenderer + PlayChordsRenderer,
);
```

And finally the magic unfolds by passing a root [`Segment`](crate::Segment) to its
[`compose()`](crate::Composer::compose) method.

```rust
// Create a 16-beat length composition
let composition_length = composer.options.ticks_per_beat * 16;
let composition = composer.compose(CompositionRoot.into_segment(0..composition_length));

// Convert it to a MIDI file and save it
MidiConverter::convert(&composition).save("./composition.mid").unwrap();
```

When plugged into your favorite midi player, the `composition.mid` file should sound somewhat like this:

<https://github.com/dousto/redact-composer/assets/5882189/9928539f-2e15-4049-96ad-f536784ee7a1>

Additionally, composition outputs support serialization/deserialization (with `serde` feature, enabled by default).

```rust
// Write the composition output in json format
fs::write("./composition.json", serde_json::to_string_pretty(&composition).unwrap()).unwrap();
```
</details>
<details open>
<summary>

## Much bigger example
</summary>

Check out [this repo](https://github.com/dousto/redact-renderer-example) for a more in depth example which utilizes
additional features to create a full length composition.
</details>
<details open>
<summary>

## Inspector
</summary>

Debugging composition outputs can quickly get unwieldy with larger compositions.
[redact-composer-inspector](https://dousto.github.io/redact-composer-inspector/) is a simple web tool that helps to
visualize and navigate the structure of [`Composition`](crate::Composition) outputs (currently only compatible with
json output).

For example, here is the [simple example loaded in the inspector](https://dousto.github.io/redact-composer-inspector/inspect?composition=examples/simple).
</details>
<details open>
<summary>

## Feature Flags
</summary>

### `default`
`derive`, `musical`, `midi`, `serde`

### `derive` <sub>default</sub>
Enable derive macro for [`Element`](crate::Element).

### `musical` <sub>default</sub>
Include [`musical`](crate::musical) domain module. ([`Key`](crate::musical::Key), [`Chord`](crate::musical::Chord),
[`Rhythm`](crate::musical::rhythm::Rhythm), etc..).

### `midi` <sub>default</sub>
Include [`midi`](crate::midi) module containing MIDI-related [`Element`](crate::Element)s and MIDI converter for
[`Composition`](crate::Composition)s.

### `serde` <sub>default</sub>
Enables serialization and deserialization of [`Composition`](crate::Composition) outputs via (as you may have guessed)
[`serde`](https://docs.rs/serde/latest/serde/).
</details>

[icon]: https://dousto.github.io/redact-composer-inspector-dev/favicon-32.png ""
[docs-badge]: https://docs.rs/redact-composer/badge.svg
[docs-link]: https://docs.rs/redact-composer
[crates.io-badge]: https://img.shields.io/crates/v/redact-composer.svg
[crates.io-link]: https://crates.io/crates/redact-composer
[ci-badge]: https://github.com/dousto/redact-composer/workflows/CI/badge.svg
[ci-link]: https://github.com/dousto/redact-composer/actions
[license-badge]: https://img.shields.io/crates/l/redact-composer.svg