# API интерфейс &arts;

## Обзор

aRts - это не просто какая-то программа, в нём поддерживается API для выполнения самых разных задач. В этом разделе будет рассказано о возможностях взаимодействия aRts с другими программами с помощью API.

Надо сразу отметить, что большинство возможностей API не зависят, от языка реализации и места вызова, поскольку они описаны на mcopidl. Вы можете использовать сервисы, которые они предлагают, на любом языке программирования, и не волноваться, работаете ли вы с локальным или с удалённым объектом. Вот список основных объектов:

core.idl

  Основные определения из MCOP, например протокол, определения объектов, трейдер, менеджер потоков и т.д.

artsflow.idl

  Содержит менеджер, управляющий соединениями аудио потоков, определение Arts::SynthModule, базы любого интерфейса с потоками, а также несколько полезных аудио объектов.

kmedia2.idl

  Здесь определен объект, который может проигрывать звук, Arts::PlayObject. Медиаплееры, наподобие noatun, смогут воспроизводить любой формат, для которого определён PlayObject. На этой базе уже реализованы форматы mp3, mpg video, midi, wav...

soundserver.idl

  Интерфейс с звуковым сервером artsd. Он называется Arts::SoundServer. Он позволяет получать потоки из сети, воспроизводить звук, создавать новые объекты aRts и т.д. Поддержка сети осуществляется прозрачным образом благодаря использованию MCOP (как и для всего прочего здесь).

artsbuilder.idl

  Этот модуль определяет основные функции управления синтезом звука, совмещая простые и более сложные объекты, за счёт составления из них структур. Это определяет основной интерфейс Arts::StructureDesc, Arts::ModuleDesc и Arts::PortDesc, которые содержат описания структур, модулей и портов. Также есть возможность получить "живую сеть объектов" из этих описаний соединений и значений, используя factory.

artsmidi.idl

  Этот модуль определяет основные функции midi, например объекты, которые создают события midi, описание события midi и Arts::MidiManager для связи "производителей" и "потребителей" событий midi и т. д. Также поддерживается прозрачная работа в сети.

artsmodules.idl

  Дополнительные фильтры, эффекты, задержки и т.д. Все они требуются для построения сложных инструментов и объектов обработки звука, которые выстраиваются из более простых объектов как из кирпичиков.

artsgui.idl

  Базовые типы для визуальных объектов. Из базового типа Arts::Widget происходят все модули графического интерфейса. Это позволяет создавать визуальные редакторы, независимые от конкретного набора библиотек. Также визуальные объекты могут служить для установки параметров напрямую через конкретный сигнал. (например значение ползунка соединено с фильтром обрезания частот). Также поддерживается прозрачная работа в сети.

aRts написан на IDL везде, где это только возможно. С другой стороны есть некоторые языкозависимые API на C++ или C. Желательно использовать только интерфейсы IDL, а другие API только при необходимости. Вот список языкозависимых API:

KNotify, KAudioPlayer (включено в libkdecore)

  Это API из KDE для случая, когда просто нужно проиграть звуковой буфер. Эта функция на C++ оптимизирована под Qt/KDE и очень простая.

libartsc

  Интерфейс C для звукового сервера. Используется для портирования программ.

libmcop

  Вот где проявляется магия MCOP. Библиотека содержит основные вещи для написания приложения MCOP, диспетчер, таймеры, а также внутренние классы для обеспечения протокола MCOP.

libartsflow

  Вместе с определением artsflow.idl, есть некоторые утилиты, например конвертация частоты дискретизации.

libqiomanager

  Интеграция MCOP в цикл событий Qt, нужно при написании приложений Qt с использованием MCOP.

## knotify

В процессе написания

## kaudioplayer

В процессе написания

## libkmid

В процессе написания

## kmedia2

В процессе написания

## sound server

В процессе написания

## artsflow

В процессе написания

## API для языка С

### Введение

C API &arts; создано для упрощения написания и портирования приложений C в интерфейс звукового сервера &arts;. Это содержит функции потоков (отправка потоков в artsd), как блокирующих (синхронных), так и асинхронных.Для многих приложений вы должны просто заменить несколько системных вызовов, совместимых с вашим звуковым устройством, на соответствующие вызовы &arts;.

Для пробы я портировал две программы - mpg123 и quake. Патчи для них можно взять здесь. Вы можете также отправлять ваши собственные патчи создателям &arts; или мультимедиа программ, чтобы они могли бы встроить поддержку &arts; в код их программ.

### Краткое обозрение

Отправка звука серверу через API делается очень просто:

1. подключите заголовочный файл: `#include <artsc.h>`

2. инициализируйте API функцией `arts_init()`

3. создайте поток `arts_play_stream()`

4. укажите требуемые параметры с помощью `arts_stream_set()`

5. отправьте аудио данные в поток функцией `arts_write()`

6. закройте поток: `arts_close_stream()`

7. освободите память, выделенную для API: `arts_free()`

Вот иллюстрация:

    #include <stdio.h>
    #include <artsc.h>
    int main()
    {
        arts_stream_t stream;
        char buffer[8192];
        int bytes;
        int errorcode;

        errorcode = arts_init();
        if (errorcode < 0)
        {
            fprintf(stderr, "arts_init error: %s\n", arts_error_text(errorcode));
            return 1;
        }

        stream = arts_play_stream(44100, 16, 2, "artsctest");

        while((bytes = fread(buffer, 1, 8192, stdin)) > 0)
        {
            errorcode = arts_write(stream, buffer, bytes);
            if(errorcode < 0)
            {
                fprintf(stderr, "arts_write error: %s\n", arts_error_text(errorcode));
                return 1;
            }
        }

        arts_close_stream(stream);
        arts_free();

        return 0;
    }

### Компиляция и сборка: artsc-config

Для упрощения сборки программ, использующих C API &arts;, используется утилита artsc-config, которая самостоятельно определяет, функции каких библиотек вам нужно импортировать, где находятся заголовочные файлы. Она вызывается так:

    artsc-config --libs

для нахождения библиотек и так:

    artsc-config --cflags

для нахождения дополнительных флагов компилятора C. Так, пример, описанный выше, можно скомпилировать из командной строки:

    cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

    cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

### Библиотеки

Ещё не готово (см. информацию в artsc.h)