# This file was auto generated by Styx.
# Do not edit this file directly.

import typing
import pathlib
from styxdefs import *
import dataclasses

V_1DSOUND_METADATA = Metadata(
    id="27afe9539a9fa717bc8a3162d9645362879cc57c.boutiques",
    name="1dsound",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


class V1dsoundOutputs(typing.NamedTuple):
    """
    Output object returned when calling `v_1dsound(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    output_file: OutputPathType | None
    """The output audio file."""


def v_1dsound(
    tsfile: InputPathType,
    prefix: str | None = None,
    encoding_16_pcm: bool = False,
    encoding_8_pcm: bool = False,
    encoding_8ulaw: bool = False,
    tper_option: float | None = None,
    fm_option: bool = False,
    notes_option: bool = False,
    notewave_option: str | None = None,
    despike_option: bool = False,
    play_option: bool = False,
    runner: Runner | None = None,
) -> V1dsoundOutputs:
    """
    Program to create a sound file from a 1D file (column of numbers).
    
    Author: AFNI Developers
    
    URL: https://afni.nimh.nih.gov/
    
    Args:
        tsfile: The input 1D time series file containing the data to transform\
            into sound.
        prefix: Prefix for the output filename, which will have '.au'\
            extension.
        encoding_16_pcm: Output in 16-bit linear PCM encoding (uncompressed).
        encoding_8_pcm: Output in 8-bit linear PCM encoding.
        encoding_8ulaw: Output in 8-bit mu-law encoding.
        tper_option: Time in seconds per time point in 'tsfile'. Allowed range\
            is 0.01 to 1.0 (inclusive). [default is 0.2s].
        fm_option: Output sound is frequency modulated between 110 and 1760 Hz\
            from min to max in the input 1D file.
        notes_option: Output sound is a sequence of notes, low to high pitch\
            based on min to max in the input 1D file. Uses pentatonic scale.
        notewave_option: Shape of the notes used. Select from [sine, sqsine,\
            square, triangle].
        despike_option: Apply a simple despiking algorithm to avoid artifacts\
            from large/small values in the input.
        play_option: Plays the sound file after it is written.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V1dsoundOutputs`).
    """
    if tper_option is not None and not (0.01 <= tper_option <= 1.0): 
        raise ValueError(f"'tper_option' must be between 0.01 <= x <= 1.0 but was {tper_option}")
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_1DSOUND_METADATA)
    cargs = []
    cargs.append("1dsound")
    cargs.append(execution.input_file(tsfile))
    if prefix is not None:
        cargs.extend([
            "-prefix",
            prefix
        ])
    if encoding_16_pcm:
        cargs.append("-16PCM")
    if encoding_8_pcm:
        cargs.append("-8PCM")
    if encoding_8ulaw:
        cargs.append("-8ulaw")
    if tper_option is not None:
        cargs.extend([
            "-tper",
            str(tper_option)
        ])
    if fm_option:
        cargs.append("-FM")
    if notes_option:
        cargs.append("-notes")
    if notewave_option is not None:
        cargs.extend([
            "-notewave",
            notewave_option
        ])
    if despike_option:
        cargs.append("-despike")
    if play_option:
        cargs.append("-play")
    ret = V1dsoundOutputs(
        root=execution.output_file("."),
        output_file=execution.output_file(prefix + ".au") if (prefix is not None) else None,
    )
    execution.run(cargs)
    return ret


__all__ = [
    "V1dsoundOutputs",
    "V_1DSOUND_METADATA",
    "v_1dsound",
]
