= OtoPerl README =

OtoPerl - live sound programming environment with Perl.

OtoPerl は perl でリアルタイムサウンド生成を行うプログラム環境です。


== Resources ==
(English or Japanese resources)
Introduction Video     http://www.youtube.com/watch?v=-ByATVMO658
Main webpage           http://drumsoft.com/otoperl/
Github Repository      https://github.com/drumsoft/OtoPerl
OtoPerl Sound Samples  http://soundcloud.com/otoperl

(Japanese resources)
YAPC::ASIA 2011 でのOtoPerlセッション http://www.youtube.com/watch?v=jVGwt6v5UXY
OtoPerlセッション 資料                http://drumsoft.com/otoperl/20111015/


== feature ==
 * Coding with Perl
   * Low learning cost for experienced user. Even a beginner can find a lot of resources to learn.
   * You can use many CPAN modules. It's rare system that you can aggregate your website's access log or analyze lexically your twitter timeline while generating sound.
 * Dynamic
   * While performance (generating sounds) with OtoPerl, you can change (or overwrite) sound generator Perl script ('OtoPerl script'). It allows "coding as playing" live performance.
 * Modules
   * Extending and combining OtoPerl prototype modules, You can quickly create new OtoPerl script.
 * with familiar environment
   * It's not tied to specific IDE. Please write OtoPerl script with familiar editors and post it to Otoperl server with 'otoperlc' client script.

== OtoPerl の特徴 ==
 * Perlコーディング
   * 経験者には学習コストが低く、初心者でも多くの学習リソースを得る事ができます。
   * 多くの便利な CPAN モジュールが使用できます。Webサイトのログを集計したり、Twitterタイムラインの字句解析を行いながらサウンド生成ができるシステムはそう多くありません。
 * ダイナミック
   * 演奏中（サウンド生成中）に、サウンド生成に使用するPerlスクリプト('OtoPerlスクリプト')を差し替える事ができます。コーディングがそのままライブ演奏である様なパフォーマンスも可能です。
 * モジュール構成
   * プロトタイプ・モジュールを拡張し組み合わせる事で、自分の OtoPerlスクリプト を素早く構成できます。
 * 使い慣れた環境で
   * OtoPerlスクリプト を書く為の専用の開発環境はありません。使い慣れたエディタでコードを書いて、 otoperlc クライアントでサーバに送信して下さい。


== requirement ==
 * Mac OS X (10.6 ? or Later ?)
 * gcc (コンパイル用, included in Mac OS X Developer Tools)

== 必須環境 ==
 * Mac OS X (10.6 ? or Later ?)
 * gcc (コンパイル用, Mac OS X の開発環境に含まれています)


== How to build ==
 * simply 'make' to build otoperld.
 * the otoperld binary included in repository is compiled for 64-bit intel CPU (x86_64).
   * I failed compile it for i386 and ppc because there are no perl binary to link. Please tell me any hints about it.

== ビルド ==
 * 'make' で otoperld をコンパイルできます。
 * リポジトリに含まれる otoperld のバイナリは 64bit intel CPU (x86_64) 向けにコンパイルされています。
   * x86_64 以外のPerlバイナリにリンクさせる方法がわからず i386 や ppc 向けのコンパイルができませんでした。ヒントご存知の方教えて下さい。


== *** WARNINGS (READ BEFORE RUN) *** ==
 * You must not expose otoperld port to network. It enable someone on the network to execute arbitrary commands on your computer.
 * in default, otoperld allows access from localhost only. If you set -a, --allow option to make other hosts accessible, be careful.

== *** ご注意 (実行前にお読み下さい) *** ==
 * otoperld のポートをネットワークに解放すると大変危険です。ネットワーク上の誰かが、あなたのコンピュータ上であらゆるコマンドを実行できる状態になります。
 * デフォルトでは、 otoperld は localhost からのアクセスのみ受け付けます。 -a, --allow オプションで接続可能なホストを指定する場合、注意して行ってください。


== Simple Tutorial ==
 1. './otoperld' to launch OtoPerl server.
   * sound processing start with test sine wave.
 2. './otoperlc samples/tutorial.pl' to post OtoPerl script to server.
   * samples/tutorial.pl contains perl code that generate sine wave and amp modulate it. the sound generation OtoPerl script running in otoperld is overwritten by it and the generating sound will be amp modulated.
 3. edit samples/tutorial.pl .
   * example: Uncomment "transform it to square wave" line, it transform sine wave to square wave.
 4. './otoperlc samples/tutorial.pl' to repost it.
   * the generating sound will be changed as coded in OtoPerl script.

== 簡単なチュートリアル ==
 1. './otoperld' で OtoPerl サーバを起動します。
   * サウンド生成が開始され、サイン波のテストトーンが鳴りだします。
 2. './otoperlc samples/tutorial.pl' で、 OtoPerlスクリプト をサーバに送信します。
   * samples/tutorial.pl にはサイン波にアンプモジュレーションを加えたコードが書かれています。otoperld がサウンド生成する OtoPerlスクリプト がこれによって上書きされ、生成されるサウンドにアンプモジュレーションがかかります。
 3. samples/tutorial.pl をエディタで変更して下さい。
   * 例: "transform it to square wave" という行のコメントを外してサイン波を矩形波に変換
 4. './otoperlc samples/tutorial.pl' で、再度 OtoPerlスクリプト をサーバに送信します。
   * エディタの変更に応じて、生成されるサウンドが変わります。


== launch options ==
otoperld [-v] [-c channels] [-r sample_rate] [-a allowed_addresses] [-p port_number] [filename]
 -v, --verbose       be verbose.
 -c, --channel 2     Number of channels OtoPerl generate. default is 2.
 -r, --rate 48000    Sampling rate of the sound OtoPerl generate. default is 48000.
 -a, --allow 192.168 Host address pattern allowed to access otoperld. default is 127.0.0.1
                     ex: 192.168.0.8 (1 host allowed, = 192.168.0.8/255.255.255.255)
                         192.168.1.0/255.255.252.0 (22 bit netmask)
                         192.168 (16 bit netmask, = 192.168.0.0/255.255.0.0)
 -p, --port 99999    Port number to listen. default is 14609.
 -f, --findfreeport  Find free port when it's already used. The found port will be put in file '.otoperld_port'.
 -o, --output x.aiff Record sounds to specified file.
 filename            OtoPerl script ran when server launched. default is 'otoperld-start.pl'.
 -i, --enable-input  Enables an audio input (from Default Input Device)

otoperlc [-h host_address] [-p port_number] filename, ...
 -p 99999          Port number to post. The number will be read from '.otoperld_port' file when '.' is specified. default is 14609.
 -h 192.168.0.1    Host name to post. default is localhost.
 When - (hyphen) specified as filename, otoperlc reads texts from STDIN and sends them.


== 起動オプション ==
otoperld [-v] [-c チャンネル数] [-r サンプルレート] [-a 接続許可アドレス] [-p ポート番号] [-o 出力ファイル名] [ファイル名]
 -v, --verbose       verboseモードになる
 -c, --channel 2     OtoPerlが生成するチャンネル数。デフォルトは 2
 -r, --rate 48000    OtoPerlが生成するサウンドのサンプリングレート。デフォルトは 48000
 -a, --allow 192.168 アクセスを許すホストアドレスパターン。デフォルトは 127.0.0.1
                     例: 192.168.0.8 (アドレスを1つ指定, = 192.168.0.8/255.255.255.255)
                         192.168.1.0/255.255.252.0 (22ビットのネットマスクを指定)
                         192.168 (16ビットのネットマスクを指定, = 192.168.0.0/255.255.0.0)
 -p, --port 99999    サーバの待ち受けるポート番号。デフォルトは 14609
 -f, --findfreeport  ポートが使用できない場合は空いているポート番号を探す。見つかったポートはファイル .otoperld_port に出力される。
 -o, --output x.aiff 指定したファイルに録音を行う。
 filename            サーバ起動時に実行されるOtoPerlスクリプト。デフォルトは otoperld-start.pl
 -i, --enable-input  オーディオ入力を有効化する (Default Input Device が使われる)

otoperlc [-h host_address] [-p port_number] filename, ...
 -p 99999          送信先ポート番号。 '.' を指定するとポート番号を .otoperld_port から読み込む。デフォルトは 14609
 -h 192.168.0.1    送信先ホストアドレス。デフォルトは localhost
 filename に - を指定すると標準入力の内容を読み込んで送信する。


== file details ==
 * otoperld               Sound generation server program for OtoPerl.
 * otoperld-start.pl      OtoPerl script that otoperld load (in default) when it launched.
 * otoperlc               Client program that post OtoPerl script to otoperld.
 * OtoPerl                Directory for modules called by otoperlc and OtoPerl script.
   * Client.pm            Modules called by otoperlc.

 * samples
   * tutorial.pl          OtoPerl script : for tutorial.
   * sample.pl            OtoPerl script : a sample.
   * silence.pl           OtoPerl script : for silence.
   * performance.pl       OtoPerl script : for performance testing.

 * README                 is you're reading.
 * HISTORY                version history.
 * LICENSE                GNU GPL 3 (or later)
 * memo.txt               a disorganized memo for developing.

 * Makefile               
 * otoperld-src           source files for otoperld.
   * audiounit.[ch]       AudioUnit launcher.
   * codeserver.[ch]      Simple HTTP Server.
   * otoperld.[ch]        the Body of otoperld.
   * aiffrecorder.[ch]    recorder function
   * main.c               otoperld launch code.
   * Makefile             

== 含まれるファイルの詳細 ==
 * otoperld               OtoPerl のサウンド生成サーバ 実行プログラム
 * otoperld-start.pl      otoperld が(デフォルトで)最初にロードする OtoPerlスクリプト
 * otoperlc               otoperld に OtoPerlスクリプト を送信するクライアント
 * OtoPerl                otoperlc や OtoPerlスクリプト から呼ばれるモジュールを保存するフォルダ
   * Client.pm            otoperlc が使用するモジュール

 * samples
   * tutorial.pl          OtoPerlスクリプト: チュートリアル用
   * sample.pl            OtoPerlスクリプト: サンプル
   * silence.pl           OtoPerlスクリプト: 無音状態
   * performance.pl       OtoPerlスクリプト: パフォーマンスのテストに使用しているもの

 * README                 is you're reading.
 * HISTORY                version history.
 * LICENSE                GNU GPL 3 (or later)
 * memo.txt               開発中の雑多なメモ

 * Makefile               
 * otoperld-src           otoperld のソースファイル
   * audiounit.[ch]       AudioUnit を起動するモジュール
   * codeserver.h[ch]     簡単なHTTPサーバ
   * otoperld.[ch]        otoperld の本体
   * aiffrecorder.[ch]    録音機能
   * main.c               otoperld の起動コード
   * Makefile