Add AGC example

[UnknownSuperficialNight]

Here is a quick AGC example

I don't know how to use set_enabled() outside the setup area, so I'm using the experimental atomicbool

close #629

[dvdsk]

so I'm using the experimental atomicbool

I rather not have examples using experimental features, since those might go away at any time.

Its clear the current method for changing a source outside of setup is hard to find or use. We will work on that, maybe by changing the API maybe with extensive documentation if no better API can be found.

For now an example showing how to do it might be very useful. So lets try and do it without atomicbool?

What you will need is PeriodicAccess it is missing an example. The best we have now is looking at the source code of the Sink.

Now we get something along the lines of this:

   let agc_enabled = Arc::new(Atomicbool::new(true));
   

   // Apply automatic gain control to the source
    let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);

   // Make the audio thread check every 5 millis if the agc needs 
   // to be enabled/disabled
   let controlled = agc_source.periodic_access(Duration::from_millis(5), 
     |periodic_access_source| {
        let agc_source = periodic_access_source.inner_mut()
        agc_source.set_enabled(agc_enabled.load(Relaxed));
     });

   // put it in sink & play
   // from some other part of the program:
   agc_enabled.store(true, Relaxed); // takes effect after 5 millis.

[UnknownSuperficialNight]

so I'm using the experimental atomicbool

I rather not have examples using experimental features, since those might go away at any time.

Its clear the current method for changing a source outside of setup is hard to find or use. We will work on that, maybe by changing the API maybe with extensive documentation if no better API can be found.

For now an example showing how to do it might be very useful. So lets try and do it without atomicbool?

What you will need is PeriodicAccess it is missing an example. The best we have now is looking at the source code of the Sink.

Now we get something along the lines of this:

   let agc_enabled = Arc::new(Atomicbool::new(true));
   

   // Apply automatic gain control to the source
    let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);

   // Make the audio thread check every 5 millis if the agc needs 
   // to be enabled/disabled
   let controlled = agc_source.periodic_access(Duration::from_millis(5), 
     |periodic_access_source| {
        let agc_source = periodic_access_source.inner_mut()
        agc_source.set_enabled(agc_enabled.load(Relaxed));
     });

   // put it in sink & play
   // from some other part of the program:
   agc_enabled.store(true, Relaxed); // takes effect after 5 millis.

Yea, when I try periodic_access I can just never get it to work

Example:

error[E0599]: no method named `inner_mut` found for mutable reference `&mut AutomaticGainControl<Decoder<BufReader<File>>>` in the current scope
  --> examples/automatic_gain_control.rs:27:53
   |
27 |             let agc_source = periodic_access_source.inner_mut();
   |                                                     ^^^^^^^^^ method not found in `&mut AutomaticGainControl<Decoder<BufReader<File>>>`

The only thing I could get the compiler to agree with is this:

let controlled =
        agc_source.periodic_access(Duration::from_millis(5), move |src| {
            src.set_enabled(agc_enabled.load(Relaxed));
        });

But of course that's not very useful as you can't use it

Here is a code snippet for context:

    let agc_enabled = Arc::new(AtomicBool::new(true));

    // Apply automatic gain control to the source
    let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);

    // Make the audio thread check every 5 millis if the agc needs
    // to be enabled/disabled
    let controlled =
        agc_source.periodic_access(Duration::from_millis(5), |periodic_access_source| {
            let agc_source = periodic_access_source.inner_mut();
            agc_source.set_enabled(agc_enabled.load(Relaxed));
        });

    // Add the controlled source to the sink for playback
    sink.append(controlled);

    // Keep the program running until playback is complete
    sink.sleep_until_end();

[dvdsk]

ahh so the compile error states the type given to the closure is already the AutomaticGainControl. So that let agc_source bit that I give you is unneeded. Try something like |agc| agc.set_enabled(agc_enabled.load(Relaxed)).

It also points to a small issue with the agc source. It should have an inner mut and inner method. They are not part of Source since a source can be generating sound, thats why I forgot them while reviewing 😅.