Announcement model requires more fields than the API does.

[marc-portier]

The model for Announcement as defined at https://github.com/brianhealey/pyamplipi/blob/main/pyamplipi/models.py#L168

requires fields media, vol_f and source_id

while the API documentation at http://api.amplipi.com/#tag--announce only requires the media field and applies sensible defaults for the others

I can provide a PR

However - am a bit confused on the vol_f: float versus vol: int usage? The API documentation does only mention the vol: int variant (as well as a vol_delta: int on zones) Its semantics and use are not quite clear to me.

[linknum23]

It looks like we need a little better documentation for this. In the meantime let me try to clarify:

vol_f is a [0.0, 1.0] factor that applies the volume to each zone based on its min and max volume. vol is [-79, 0] in decibels and is overrides about each zone's min and max volume.

In almost all use cases vol_f is better, it was just added later to the API once we figured out how to add a min and max volume config to each zone.

vol is potentially useful in an emergency situation where you want to blare the volume no matter what the setting is.

[marc-portier]

@linknum23 sorry for this follow up - just want to make sure I understand

This is what I understand: both vol and vol_f are functionally aiming the same, ie they are alternatives to set the volume to be applied.

• the argument vol takes an integer in db to set the volume ignoring any min-max settings (per zone?)
• the vol_f takes a float between 0 and 1 to interpolate the volume-value between min and max (I assume with something like vol = min + vol_f * (max - min)

I am assuming these statements are about the REST API model; so both could be sent down to the server in the body, right?

What is confusing / not clear however:

• What happens if I sent both? vol_f gets ignored and the vol takes precedence?
• Where do I find / modify these min-max (zone) settings? I find no reference to them in http://api.amplipi.com/#tag--zone nor http://api.amplipi.com/#post-/api/load Or are they hard-coded in some way?
• Where can I submit any PR for the API documentation website? If this is part of https://github.com/micro-nova/AmpliPi then maybe hint me to the correct parts? Is there some swagger/openapi being generated?

Finally:

• It would be grand if you could also confirm the main claim of this topic: namely that only the media field is required (as I have experienced through curl testing) and that thus the Announcement model in this project should adopt itself?

[linknum23]

What happens if I sent both? vol_f gets ignored and the vol takes precedence?

Exactly!

Where do I find / modify these min-max (zone) settings? I find no reference to them in http://api.amplipi.com/#tag--zone nor http://api.amplipi.com/#post-/api/load Or are they hard-coded in some way?

We forgot to update this manually for the 0.1.8 release. Its a bit of a manual process to update all of the examples and needs some automation. You should find this documentation to be up to date on your amplipi device at http://amplipi.local/doc. It is generated at runtime from the contents of two files: amplipi/app.py and amplipi/models.py. Some of the example responses are probably out of date.

Where can I submit any PR for the API documentation website? If this is part of https://github.com/micro-nova/AmpliPi then maybe hint me to the correct parts? Is there some swagger/openapi being generated?

It is part of the main AmpliPi repo, specifically this file: https://github.com/micro-nova/AmpliPi/blob/main/docs/amplipi_api.yaml

t would be grand if you could also confirm the main claim of this topic: namely that only the media field is required (as I have experienced through curl testing) and that thus the Announcement model in this project should adopt itself?

Yup you only need to specify the media field!