ExportOsc(外部との OSC 通信)

このページは過去の情報となります。
新しいスクリプトリファレンスはこちらになります。

Open Sound Control プロトコル（OSC）を用いて外部アプリケーションとのメッセージングを行うクラスです。

OSC 機能を利用する場合、タイトル画面>詳細設定の VCI タブ内から OSC 送信機能、OSC 受信機能 を有効化してください。
OSC Message の送信/受信先は、タイトル画面>詳細設定の VCI タブ内の OSCメッセージ受信ポート、OSCメッセージ送信ポート から設定できます。
- 受信ポートのデフォルト値は 19100 です。
- 送信ポートのデフォルト値は 18100 です。
OSC Message の送信は、 localhost 内でのみ行えます。
OSC Message を設定なしで受信できるのは、 localhost 内のみです。
バーチャルキャスト v2.3.6a 以降で動作します。
現在、この API はPC版でのみ動作します。
この API を使ったサンプルはこちらのページにあります。

メンバ変数・関数一覧

vci.osc
名前	説明
types	送受信できるOSC Argumentの型の列挙子を表すクラスを返す
IsSendEnabled	呼び出し元のVCIインスタンスのOSC Message送信機能の有効フラグを取得
IsReceiveEnabled	呼び出し元のVCIインスタンスのOSC Message受信機能の有効フラグを取得
SendAsciiString	ASCII文字列をOSC Messageとして送信
SendInt32	32ビット整数をOSC Messageとして送信
SendFloat32	32ビット浮動小数をOSC Messageとして送信
SendUtf8String	UTF-8文字列を表すバイト列をOSC Messageとして送信
SendMessage	引数無しのOSC Messageを送信
SendMessage	複数個かつ任意の組み合わせのOSC Argumentを持つOSC Messageを送信
RegisterMethod	指定のOSC Addressに送られてきたOSC Messageを受信したときに呼びだされる関数を登録する
UnregisterMethod	指定のOSC Addressに登録されている関数の登録を解除する

types

vci.osc.types ExportOscType

説明

送受信できる OSC Argument の型の列挙子を表すクラスを返します。
vci.osc.SendMessage や vci.osc.RegisterMethod で送受信する OSC Argument を指定する際に利用します。

列挙子一覧
types.String	ASCII 文字列
types.Int32	32bit 整数
types.Float32	32bit 浮動小数
types.BlobAsUtf8	UTF-8 文字列を表すバイト列

IsSendEnabled

vci.osc.IsSendEnabled fun(): bool

説明

呼び出し元の VCI インスタンスの OSC Message 送信機能の有効フラグを取得します。
OSC Message 送信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
- disabled の場合、すべての VCI インスタンスにおいて false が返されます。
- enabled の場合、すべての VCI インスタンスにおいて true が返されます。
- creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

サンプル

main.lua

local isEnabled = vci.osc.IsSendEnabled()
print(isEnabled)

IsReceiveEnabled

vci.osc.IsReceiveEnabled(): bool

説明

呼び出し元の VCI インスタンスの OSC Message 受信機能の有効フラグを取得します。
OSC Message 受信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
- disabled の場合、すべての VCI インスタンスにおいて false が返されます。
- enabled の場合、すべての VCI インスタンスにおいて true が返されます。
- creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

サンプル

main.lua

local isEnabled = vci.osc.IsReceiveEnabled()
print(isEnabled)

SendAsciiString

vci.osc.SendAsciiString fun(address: string, argument: string)

引数

address	OSC Message の送信先の OSC Address
argument	OSC Argument として送信する string

説明

argument をASCII文字列に変換し、address に OSC Message として送信します。
- こちらの関数では英字文字列のみ送信することができます。日本語文字列を送信したい場合、vci.osc.SendUtf8String を利用してください。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
argument が null の場合、送信に失敗します。この際、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendAsciiString("/test/sendstring", "hello")

SendInt32

vci.osc.SendInt32 fun(address: string, argument: number)

引数

address	OSC Message の送信先の OSC Address
argument	OSC Argument として送信する number

説明

argument を 32bit 整数に変換し、address に OSC Message として送信します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendInt32("/test/sendint", 100)

SendFloat32

vci.osc.SendFloat32 fun(address: string, argument: number)

引数

address	OSC Message の送信先の OSC Address
argument	OSC Argument として送信する number

説明

argument を 32bit 浮動小数に変換し、address に OSC Message として送信します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendFloat32("/test/sendfloat", 3.14)

SendUtf8String

vci.osc.SendUtf8String fun(address: string, argument: string)

引数

address	OSC Message の送信先の OSC Address
argument	OSC Argument として送信する string

説明

argument を UTF-8 としてエンコードしたバイト列に変換し、address に OSC Message として送信します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
argument が null の場合、送信に失敗します。この際、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendUtf8String("/test/sendutf8", "こんにちわ")

SendMessage(引数無しメッセージの送信)

vci.osc.SendMessage fun(address: string)

引数

address	OSC Message の送信先の OSC Address

説明

address に引数無しの OSC Message を送信します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendMessage("/test/sendmessage")

SendMessage(複数引数を含むメッセージの送信)

vci.osc.SendMessage fun(address: string, arguments: Table)

引数

address	OSC Message の送信先の OSC Address
arguments	送信する OSC Argument の型と値を列挙したテーブル

arguments テーブルは、以下のフォーマットで記述します。

arguments_table.lua

-- {
--   {(OSC Argumentの型), (OSC Argumentの値)}
--   ..., 送信するOSC Argumentの個数分繰り返す
-- }
 
-- 例：String, Int32, Float32, BlobAsUtf8をOSC Messageとして送信する
arguments = 
{
  {vci.osc.types.String, "hello"},
  {vci.osc.types.Int32, 10},
  {vci.osc.types.Float32, 3.14},
  {vci.osc.types.BlobAsUtf8, "こんにちわ"},
}

説明

argumentsテーブルで指定した複数の OSC Argumentを一つの OSC Message としてaddressに送信します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

main.lua

vci.osc.SendMessage("/test/sendMultiple", 
{
  {vci.osc.types.String, "hello"},
  {vci.osc.types.Int32, 10},
  {vci.osc.types.Float32, 3.14},
  {vci.osc.types.BlobAsUtf8, "こんにちわ"}
})

RegisterMethod

vci.osc.RegisterMethod fun(address: string, callback: function, argumentTypes: Table)

引数

address	OSC Message の受信を待ち受ける OSC Address
callback	OSC Message を受信したときに実行されるコールバック
argumentTypes	受信する OSC Message に含まれる OSC Argument の型を順番に列挙したテーブル

argumentTypes テーブルは、以下のフォーマットで記述します。

argument_types_table.lua

-- {
--   (OSC Argumentの型), 
--   ..., 受信する OSC Message の OSC Argument の個数分繰り返す
-- }
 
-- 例：String, Int32, Float32, BlobAsUtf8を受信する場合
argumentTypes = 
{
  vci.osc.types.String,
  vci.osc.types.Int32,
  vci.osc.types.Float32,
  vci.osc.types.BlobAsUtf8,
}

説明

argumentsに OSC Message が送られてきたときに呼びだされる関数を登録します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、登録に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
VC クライアント側で予約済みの一部 OSC Address に対して関数の登録を試みた場合、登録に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
同一の OSC Address に対して、同じ VCI インスタンスから一つのみ関数を登録できます。
- 別 VCI インスタンスからの登録であった場合、重複は許容されます。
- 同じ OSC Address に複数の関数が重複して登録されている場合、その OSC Address に OSC Message が到達したときに登録されているすべての関数が実行されます。

main.lua

-- ASCII string を一個受信する
function echo(content)
  print(content)
end
 
vci.osc.RegisterMethod("/test/echo", echo, {vci.osc.types.String})
 
-- float を二個受信する
function show_point(x, y)
  print(x..", "..y)
end
 
vci.osc.RegisterMethod("/test/showPoint", show_point, {vci.osc.types.Float32, vci.osc.types.Float32})

UnregisterMethod

vci.osc.UnregisterMethod fun(address: string)

引数

address	登録解除したい関数が登録されている OSC Address

説明

RegisterMethodでaddressに登録した関数の登録を解除します。
address が null の場合、または不正なフォーマットの OSC Address であった場合、登録解除に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

main.lua

-- ASCII string を一個受信する
function echo(content)
  print(content)
end
 
vci.osc.RegisterMethod("/test/echo", echo, {vci.osc.types.String})
 
-- VCI が Use されたとき、関数 echo の "/test/echo" への登録を解除する
function onUse(item)
  vci.osc.UnregisterMethod("/test/echo")
end