# NAME

Music::Voss - functions for fractal noise generation functions

# SYNOPSIS

```
use List::Util qw(max sum0);
use Music::Voss qw(bitchange powers);
# roll up to 3 dice as the bits change between the $x values
my $bc = bitchange(
roll => sub { 1 + int rand 6 },
rollers => 3,
);
for my $x (0..21) {
printf "%d %d\n", $x, $bc->($x);
}
# call functions when x % 2**funcnum == 0
my $genf = powers( calls => [
sub { int rand 2 }, # k=0, 2**k == 1 (every value)
sub { int rand 2 }, # k=1, 2**k == 2 (every other value)
sub { int rand 2 }, # k=2, 2**k == 4 ...
sub { int rand 2 }, # k=3, ...
...
]);
my $geny = powers(
calls => [ sub { 5 - int rand 10 }, ... ],
summer => sub { max 0, sum0 @_ },
);
for my $x (0..21) {
printf "%d %d %d\n", $x, $genf->($x), $geny->($x);
}
# or to obtain a list of values (NOTE TODO FIXME the powers() generated
# functions maintain state and there is (as yet) no way to inspect or
# reset that state; for now generate a new function if needed.)
my @values = map { $genf->($_) } 0..21;
```

Consult the `eg/`

and `t/`

directories under this module's distribution for more example code.

# DESCRIPTION

This module contains functions that generate functions that can be called with numbers to generate other numbers. Given how hopelessly vague this may sound, let us move on to the

# FUNCTIONS

These are not exported, and must be manually imported or called with the full module path.

**bitchange**-
Returns a function that will run a

`roll`

method for each changed bit of a given number of`rollers`

between the passed value and the previous one, then returns the sum of those numbers (via the`summer`

function, by default`sum0`

of List::Util). The default`roll`

is a six-sided die producing integers from`0`

through`5`

, and the default number of`rollers`

is`3`

. The`roll`

call is called with two arguments, the given number and the index of the die being updated. The given number will be`undef`

when there is no previous value to calculate bit changes from; this is a concern when the`roll`

call is concerned with the number passed to the generated function:`my $fun = bitchange( roll => sub { my ($n, $dienum) = @_; if (defined $n) { ... $fun->(0); # no previous, so $n undef in roll call $fun->(1); # $n now available`

The generated function ideally should be fed sequences of integers that increment by one, though other sequences will produce other bit change patterns. Too large a number of

`rollers`

may run into problems, possibly around 32 or 64, depending on how perl is compiled and thus how many bits are available in a given integer. **powers**-
This function returns a function that in turn should be called with (ideally successive) integers. The generated function uses powers-of-two modulus math on the array index of the list of given

`calls`

to determine when the result from a particular call should be saved to an array internal to the generated function. A custom`summer`

function may be supplied to**powers**that will sum the resulting list of numbers; the default is to call`sum0`

of List::Util and return that sum. The`e`

parameter allows the exponent to be set; the default is`2`

.The

`calls`

functions are passed two arguments, the given number, and the array index that triggered the call.`calls`

functions probably should return a number. Typically, the`calls`

return random values, though other patterns are certainly worth experimenting with, such as a mix of random values and other values that are iterated through:`use Music::AtonalUtil; my $atu = Music::AtonalUtil->new; my @values = qw/0 0 2 1 1 2 0/; my $genf = powers( calls => [ sub { 1 - int rand 2 }, # 1 sub { 0 }, # 2 sub { 1 - int rand 2 }, # 4 sub { 1 - int rand 2 }, # 8 $atu->nexti( \@values ) # 16 ] );`

The generated function ideally should be fed sequences of integers that increment by one. This means that the slower-changing values from higher array indexed

`calls`

will persist through subsequent calls. If this is a problem, consider instead the **powers_stateless**-
function, which is exactly like

**powers**, only it does not keep state through repeated calls the the returned function. Likely useful for rhythmic (or MIDI velocity) related purposes, assuming those purposes can be shoehorned into the powers-of-two modulus model of the**powers**function. And they can be! A mod 12 rhythm would be possible via something like:`my $mod12 = powers_stateless( calls => [ sub { my ( $n, $k ) = @_; $n % 12 == 0 ? 1 : 0 }, ] ); for my $x (0..$whatevs) { my $y = $mod12->($x); ...`

Though, any such math must bear in mind that

`calls`

beyond the first are only called on every 2nd, 4th, etc. input value (assuming as ever that the input values are a list of integers that being on an even value and increment by one for each successive call). **weierstrass**-
This function returns a function that calculates Fourier like numbers only with exponents instead of linear harmonics. The required parameters are

`r`

,`H`

, and`N`

`r should be 0 < r <= 1 H should be 0 < H <= 1 N should be a positive integer number of harmonics`

Example use

`my $w = weierstrass( r => 0.5, H => 1.0, N => 32 ); for my $t (0 .. 100) { ... = $w->( $t / 10 ); ... }`

Unlike the previous functions the function returned by

**weierstrass**is typically fed floating point values instead of integers.Optionally a phase function can be supplied that accepts both the current value

`$t`

, a custom value`$x`

that sets the strength of the effect, and`$k`

the current harmonic number of`N`

. The original parameters are also available.`use Math::Trig qw(pi); my $w = weierstrass( r => 0.5, H => 1.0, N => 32, phase => sub { my ( $t, $x, $k, %params ) = @_; return $x * pi * rand() * $params{r}**( $k * $params{H} ); } ); my $x = ...; for my $t (...) { ... = $w->( $t, $x ); ... }`

# BUGS

## Reporting Bugs

Please report any bugs or feature requests to `bug-music-voss at rt.cpan.org`

, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Music-Voss.

Patches might best be applied towards:

https://github.com/thrig/Music-Voss

## Known Issues

The functions returned by some functions of this module probably should not be used in a threaded environment, on account of unknown results should multiple threads call the same function around the same time. This could be a feature for experimental musical composition.

May need multiple return values from the function returning functions, with the remaining functions being means to reset or otherwise interact with any state maintained by the function. (In the meantime make a new object to reset things to a known state.)

The lack of testing. (Bad input values, whether anything sketchy is going on with the closures, etc.)

Probably should make a distinction between the initial element function and those called for different input numbers, as one may want particular starting values, or a different seed function called.

# SEE ALSO

MIDI::Simple or Music::Scala or Music::LilyPondUtil have means to convert numbers (such as produced by the functions returned by the functions of this module) into MIDI events, frequencies, or a form suitable to pass to lilypond. Music::Canon (or the `canonical`

program by way of App::MusicTools) may also be of interest, as well as Music::AtonalUtil for various music related functions.

Music::RecRhythm is a similar if different means to change rhythms over time. Music::VoiceGen is a more markov approach.

# REFERENCES

Gardner M. White and brown music, fractal curves and one-over-f fluctuations. Scientific American. 1978 Apr;238(4):16-27.

Loy G. Musimathics: the mathematical foundations of music. Mit Press; 2011 Aug 19.

# AUTHOR

thrig - Jeremy Mates (cpan:JMATES) `<jmates at cpan.org>`

# COPYRIGHT AND LICENSE

Copyright (C) 2016,2018 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause