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