ATOMIC AI AUDIO AND MUSIC SPEC

RULE: This document defines the complete and binding audio and music system of the Atomic language.
RULE: Only the functions and constants listed in this document exist.
RULE: No additional audio or music functions, arguments, or behaviors exist.
RULE: All rules defined here are mandatory.

GENERAL AUDIO RULES
RULE: Audio playback is handled exclusively through dedicated audio functions.
RULE: Audio functions do not return values unless explicitly stated.
RULE: Audio playback is independent from the drawing system.
RULE: Audio playback may occur inside or outside CICLO CONTINUO.

SOUNDS AND AUDIO FUNCTIONS
suona --> (SUONO:) (RIPETI SUONO:) (INTONAZIONE:) (VOLUME:)
nome_variabile = ottieni suono --> (NOME: "")
ferma questo suono --> (NOME:)
elimina suono --> (NOME:)
interrompi suono --> (SUONO:)
nome_variabile = ottieni risultato controllo se sta suonando --> (SUONO:)
nome_variabile = ottieni risultato controllo se questo suono è in pausa --> (NOME:) 
nome_variabile = ottieni posizione attuale traccia del suono --> (NOME:)
nome_variabile = ottieni lunghezza traccia del suono --> (NOME:)
suona melodia --> (NOTE: Do-Re-Mi- - -) (SUONO:) (BPM:) (RIPETI MELODIA:) (VOLUME:)
modifica melodia --> (SUONO:) (BPM:) (RIPETI MELODIA:) (VOLUME:)
suona audio dinamico --> (NOME:) (SUONO:) (INOTNAZIONE:) (VOLUME:) (X:) (Y:) (Z:) (RIPETI SUONO:) (POSIZIONE TRACCIA:)
metti in pausa questo suono --> (NOME:) 
riprendi a suonare questo suono --> (NOME:)
nome_variabile = ottieni valore intonazione di --> (SUONO:)
nome_variabile = ottieni volume microfono
modifica audio dinamico --> (NOME:) (INTONAZIONE:) (VOLUME:) (X:) (Y:) (Z:) (POSIZIONE TRACCIA:)
modifica posizione ascoltatore --> (X:) (Y:) (Z:)

BASIC SOUND PLAYBACK
RULE: A sound is played using the following function.
suona --> (SUONO:) (RIPETI SUONO:) (INTONAZIONE:) (VOLUME:)
RULE: SUONO specifies the sound to be played.
RULE: RIPETI SUONO is a boolean constant.
RULE: INTONAZIONE is a numeric value that modifies pitch.
RULE: VOLUME is a fuzzy value.
RULE: VOLUME may be expressed as:
a number between 0 and 1
a percentage value (converted internally to a value between 0 and 1)
RULE: Arguments may be omitted and default values are used.

MUSICAL NOTES
RULE: Atomic provides predefined musical note constants.
RULE: Musical notes are used as numeric pitch values.
RULE: Musical notes may be multiplied by numeric values to change octave.
RULE: The following note constants exist.
Do  
Do diesis  
Re  
Re diesis  
Mi  
Fa  
Fa diesis  
Sol  
Sol diesis  
La  
La diesis  
Si  
RULE: Notes may be combined with numeric multipliers.
RULE: Example semantics include octave changes.

PREDEFINED SOUND CONSTANTS
RULE: The following predefined sound constants exist.
RULE: Each sound constant references a predefined audio file bundled with Atomic.
RULE: Sound constants may be used wherever a SUONO argument is required.
suono beep1 - predefined audio file reference: interface sound
suono beep2 - predefined audio file reference: interface sound
suono beep3 - predefined audio file reference: interface sound
suono miao - predefined audio file reference: cat sound
suono bau - predefined audio file reference: dog sound
suono quak - predefined audio file reference: goose sound
suono beee - predefined audio file reference: sheep sound
suono squit - predefined audio file reference: mouse sound
suono muuu - predefined audio file reference: cow sound
suono uhahah - predefined audio file reference: monkey sound
suono hiii - predefined audio file reference: horse sound
suono hiho - predefined audio file reference: donkey sound
suono driiin - predefined audio file reference: doorbell sound
suono errore - predefined audio file reference: negative interface sound
suono ok - predefined audio file reference: positive interface sound
suono nota piano - predefined audio file reference: piano note Do4
RULE: No other predefined sound constants exist.

STOPPING AND REMOVING SOUNDS
RULE: A specific playing sound may be stopped using:
ferma questo suono --> (NOME:)
RULE: This pauses the sound identified by NOME.

RULE: A sound resource may be removed using:
elimina suono --> (NOME:)
RULE: This removes the sound from memory.

RULE: All instances of a sound may be interrupted using:
interrompi suono --> (SUONO:)
RULE: This stops all sounds using the specified SUONO.

PAUSING AND RESUMING SOUNDS
RULE: A specific sound may be paused using:
metti in pausa questo suono --> (NOME:)
RULE: A paused sound may be resumed using:
riprendi a suonare questo suono --> (NOME:)
FORBIDDEN: Pausing or resuming non-dynamic sounds.

MELODY PLAYBACK
RULE: A melody is played using the following function.
suona melodia --> (NOTE:) (SUONO:) (BPM:) (RIPETI MELODIA:) (VOLUME:)
RULE: NOTE is a text value defining the musical sequence.
RULE: Notes inside NOTE are separated by hyphens "-".
RULE: A dash "-" represents a pause.
RULE: BPM defines the tempo of the melody.
RULE: RIPETI MELODIA is a boolean constant.
RULE: SUONO defines the instrument sound.
RULE: VOLUME is a fuzzy value.

MELODY MODIFICATION
RULE: A currently playing melody may be modified using:
modifica melodia --> (SUONO:) (BPM:) (RIPETI MELODIA:) (VOLUME:)
RULE: Arguments not specified remain unchanged.

DYNAMIC AUDIO PLAYBACK
RULE: Atomic supports spatial and dynamic audio playback.
RULE: Dynamic audio playback uses the following function.
suona audio dinamico --> (NOME:) (SUONO:) (INTONAZIONE:) (VOLUME:) (X:) (Y:) (Z:) (RIPETI SUONO:) (POSIZIONE TRACCIA:)
RULE: NOME identifies the dynamic audio instance.
RULE: SUONO specifies the sound resource.
RULE: INTONAZIONE modifies pitch dynamically.
RULE: VOLUME is a fuzzy value.
RULE: X, Y, and Z define the spatial position of the sound.
RULE: RIPETI SUONO is a boolean constant.
RULE: POSIZIONE TRACCIA defines the playback position within the sound.

AUDIO FILE SUPPORT
RULE: Atomic supports audio files in .ogg format only.
RULE: Other audio formats are not supported.
RULE: Audio files may be referenced using:
relative paths
absolute paths
RULE: If no extension is specified, Atomic attempts automatic resolution.

DESIGN PRINCIPLES
RULE: The audio system is designed to:
support simple sound playback
support music and melodies
support spatial and dynamic audio
remain suitable for didactic use

FORMAL CLOSURE
RULE: The audio and music system of Atomic is limited to the functions listed in this document.
RULE: Any audio or music function or argument not listed here:
does not exist
must not be inferred
must not be generated