`AudioFrame` internal `used_size` marker accessors

[microbit-carlos]

AudioFrame has an internal marker to indicate how much data has been recorded into it already.

This marker is moved via:

• microphone.record() and microphone.record_into()
• Accessing data from the AudioFrame via indexes, eg my_audioframe[n]
• The AudioFrame.copyfrom() method
  • AudioFrame.copyfrom() should move the internal used_size marker #190
• An AudioFrame copy constructor or clone method
  • AudioFrame deep copy #189
• Did I miss anything else?

We still need to document this in the docs, and having a document hidden feature without a way to access it is not ideal.

We were waiting for cases when having these accessors was beneficial, mostly following the general philosophy of "it's easier to add something later than it is to remove it or modify it".

Cases where we would have found these accessors useful:

• When trying out the current API, the main cases were due to the bugs linked above
• If we were to add the buffer_offset parameter to microphone.record_into(), then (Should microphone.record_into() have an additional duration and/or buffer_offset parameters? #197) it would be useful for cases like this:
  microphone.record_into(my_audioframe, buffer_offset=my_audioframe.get_position())
• If we were to add an offset parameter to AudioFrame.copyfrom() (Effective way to get data in and out of an AudioFrame #194), then it would be useful to understand where to continue from (af.copyfrom(buffer, af.get_position())
• Another useful case with the current API, is if we want to copy data into an AudioFrame already used and set the marker to the end of the copied data

  af = microphone.record(4000)
  af.copyfrom(other_audio_data)
  af.set_position(len(other_audio_data))

In the case we'd like to implement this, we have a couple options:

1. seek(offset, whence) and tell() from the Python file object
2. set_position() and get_position()
   • Or similar to this, but with a different word than "position"

Option 1) is more standard, but option 2) might be simpler to understand, and matches similar accessors already used in the micro:bit API.
So, my vote would be for option 2).

[microbit-carlos]

While being able to provide accessors to the current implementation of AudioFrame will be beneficial, this new proposal would replace this suggestion:

• AudioFrame proposal: Reference external buffer  #205

[microbit-carlos]

This has been superseded by:

• AudioFrame proposal: Reference external buffer  #205 (comment)