documentation.conf

extensionName = "sound"
markdownTemplate = """
# NetLogo Sound extension

This package contains the NetLogo sound extension.

{{> BUILDING.md}}

{{> USING.md}}

## Primitives

{{#contents}}{{#prims}}
[`{{name}}`](#{{primitive.extensionName}}{{primitive.name}})
{{/prims}}{{/contents}}

{{#primitives}}
{{> primTemplate}}
{{/primitives}}

{{> INSTRUMENTS.md}}

{{> LICENSE.md}}
"""
primTemplate = """
### `{{name}}`

```NetLogo
{{#examples}}
{{primitive.fullName}}{{#args}} {{name}}{{/args}}
{{/examples}}
```

{{{description}}}
"""
filesToIncludeInManual = [ "USING.md", "primitives", "INSTRUMENTS.md" ]
primitives = [
  {
    name: drums,
    type: reporter,
    returns: list,
    description: """
Reports a list of the names of the [47 drums](#drum-names)
for use with `sound:play-drum`.
"""
  },
  {
    name: instruments,
    type: reporter,
    returns: list,
    description: """
Reports a list of the names of the [128 instruments](#instrument-names)
for use with `sound:play-note`, `sound:play-note-later`,
`sound:start-note` and `sound:stop-note`.
"""
  },
  {
    name: play-drum,
    type: command,
    arguments: [ { name: drum, type: string }, { name: velocity, type: number } ],
    description: """
Plays a drum.

Example:

```NetLogo
sound:play-drum "ACOUSTIC SNARE" 64
```
"""
  },
  {
    name: play-note,
    type: command,
    arguments: [
      { name: instrument, type: string },
      { name: keynumber, type: number },
      { name: velocity, type: number },
      { name: duration, type: number }
    ],
    description: """
Plays a note for a specified duration, in seconds. The agent does not
wait for the note to finish before continuing to next command.

```NetLogo
;; play a trumpet at middle C for two seconds
sound:play-note "TRUMPET" 60 64 2
```
"""
  },
  {
    name: play-note-later,
    type: command,
    arguments: [
      { name: delay,      type: number },
      { name: instrument, type: string },
      { name: keynumber,  type: number },
      { name: velocity,   type: number },
      { name: duration,   type: number }
    ],
    description: """
Waits for the specified delay before playing the note for a specified
duration, in seconds. The agent does not wait for the note to finish
before continuing to next command.

Example:

```NetLogo
;; in one second, play a trumpet at middle C for two seconds
sound:play-note-later 1 "TRUMPET" 60 64 2
```
"""
  },
#   {
#     name: play-sound,
#     type: command,
#     arguments: [ { name: filename, type: string } ]
#     description: """
# Plays a sound file. It does not wait for the sound file to finish
# before moving to the next command. It supports WAV, AIFF, and AU
# files.
# 
# Example:
# 
# ```NetLogo
# ;; plays the beep.wav sample file
# sound:play-sound "beep.wav"
# ```
# """
#   },
#   {
#     name: play-sound-and-wait,
#     type: command,
#     arguments: [ { name: filename, type: string } ],
#     description: """
# Plays a sound file, waiting for it to finish playing before moving to
# the next command. It supports WAV, AIFF, and AU files.
# 
# Example:
# 
# ```NetLogo
# ;; plays the beep.wav sample file, waiting for it to finish before
# ;; playing boop.wav
# sound:play-sound-and-wait "beep.wav"
# sound:play-sound-and-wait "boop.wav"
# ```
# """
#   },
#   {
#     name: play-sound-later,
#     type: command,
#     arguments: [
#      { name: filename, type: string },
#      { name: delay,    type: number }
#     ],
#     description: """
# Plays a sound file after the specified delay, in seconds. It does not
# wait for the sound file to play or finish before moving to the next
# command. It supports WAV, AIFF, and AU files.
# 
# ```NetLogo
# ;; plays the beep.wav sample file one second from now
# sound:play-sound-later "beep.wav" 1
# ```
#   },
#   {
#     name: start-note,
#     type: command,
#     arguments: [
#       { name: instrument, type: string },
#       { name: keynumber, type: number },
#       { name: velocity, type: number }
#     ],
#     description: """
# Starts a note.
# 
# The note will continue until `sound:stop-note`, `sound:stop-instrument` or `sound:stop-music` is called.
# 
# Example:
# 
# ```NetLogo
# ;; play a violin at middle C
# sound:start-note "VIOLIN" 60 64
# 
# ;; play a C-major scale on a xylophone
# foreach [60 62 64 65 67 69 71 72] [
#   sound:start-note "XYLOPHONE" ? 65
#   wait 0.2
#   sound:stop-note "XYLOPHONE" ?
# ]
# ```
# """
#   },
#   {
#     name: stop-note,
#     type: command,
#     arguments: [
#       { name: instrument, type: string },
#       { name: keynumber, type: number }
#     ],
#     description: """
# Stops a note.
# 
# Example:
# 
# ```NetLogo
# ;; stop a violin note at middle C
# sound:stop-note "VIOLIN" 60
# ```
# """
#   },
#   {
#     name: stop-instrument,
#     type: command,
#     arguments: [ { name: instrument, type: string } ]
#     description: """
# Stops all notes of an instrument.
# 
# Example:
# 
# ```
# ;; stop all cello notes
# sound:stop-instrument "CELLO"
# ```
# """
#   },
#   {
#     name: stop-music,
#     type: command,
#     description: "Stops all notes."
#   }
]