投稿日

カメラで検出した音や動体の記録を確認できるソラカメ API

こんにちは、ソリューションアーキテクトの内田（ニックネーム: jet）です。

以下のブログで Soracom Cloud Camera Services（以下、ソラカメ）のAPIとWebコンソールのアップデートを紹介しました。

クラウドカメラの映像を自由にコントロール 〜ソラカメ API・Webコンソールの一般公開〜 – SORACOM公式ブログ
こんにちは、ソラコムでソラカメのプロダクトマネージャをしている五十嵐 (ニックネーム: ash )です。 本日は、カメラ映像をクラウドへ常時録画・再生できる Soracom Clou…
blog.soracom.com

今回はこの ソラカメ API（以下、API）に「カメラで検出されたイベント（音や動体検出など）」を取得できるイベント一覧APIが追加されましたので紹介します。

今回追加されたAPIのAPIリファレンスはこちらです。

このAPIを利用すると例えば、音や動体検出などのイベントを検知した瞬間の静止画や、映像だけを取得できるようになります。

イベントが発生した期間の動画をダウンロードして手元に保存したり、イベント検出時の静止画を時系列で並べることで、変化の様子を記録するなど新しいソリューションのきっかけとして利用できます。

弊社の社員が花壇によく動物の足跡が付いているのを見つけて、ソラカメを設置して監視をしたところ、ある朝に新しい足跡を発見し、通常であれば昨夜の動画を全部見て確認するところを、最初にイベント一覧を確認して猫が写っているところがあったので、その周辺の動画を確認したところ、直ぐに猫を特定することができました。

この様に、このAPIを利用することによって、目的の動画に効率的にアクセスできるようになるので、皆様是非ご活用ください。

イベント一覧 API

ソラカメのライセンスを紐づけているカメラでモーション検知設定を有効化していれば、カメラで検出されたイベントに関する情報が取得可能になります。

すでにATOM Cam 2やATOM Cam Swingをお持ちの方へ:
ソラカメのライセンスは、ライセンス単体でオンラインでお求めいただくことができます。詳しくは「ソラカメ」ライセンス単独販売開始のお知らせをご覧ください。

SORACOMユーザーコンソールで確認すると、以下が確認できます。

  • 日時：イベントが検出された日時
  • デバイスタイプ：イベントが検出されたデバイスの種類
  • デバイス：イベントが検出されたデバイス。デバイス詳細画面へのリンクになっています
  • イベントタイプ：検出されたイベントの種類
  • イベント画像：イベントが検出された際の画像。有効期限があります。
  • 画像をダウンロードするボタン：イベント画像に表示されている画像をダウンロードできます。有効期限があります。
  • 映像を確認するボタン：イベントを検出した開始時刻から終了時刻までをストリーミング映像で確認できます。ここで映像を確認すると月72 時間分の再生時間が消費されます。

ソラカメ対応カメラで検出されたイベントの一覧を取得する

実際にSORACOM CLIを利用して、イベント一覧を取得するAPIを実行してみます。
SORACOM CLIは最新のバージョンを利用してください。

実行するAPI

ソラカメ対応カメラで検出されたイベントの一覧を取得します (SoraCam:listSoraCamDeviceEvents)

CLIコマンド サンプル

soracom sora-cam devices events list

CLIコマンド実行結果 サンプル（一部抜粋 / 編集済み）

[
    {
        "deviceId": "7CXXXXXXXX0E",
        "deviceType": "atomCamV2",
        "eventId": "ef2222395b8b40b1915da5af100b983e",
        "eventInfo": {
            "atomEventV1": {
                "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281135_1670281135000_13_1_0/311989cf93bf4afa9c282b6a2a682525.jpg",
                "startTime": 1670281135000,
                "status": "recording",
                "type": "cloudStorage"
            },
            "infoType": "atomEventV1"
        },
        "time": 1670281135000
    },
    {
        "deviceId": "7CXXXXXXXX89",
        "deviceType": "atomCamV2",
        "eventId": "9522226d9b8b41889f1827ad26b3a028",
        "eventInfo": {
            "atomEventV1": {
                "endTime": 1670281129000,
                "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX89/2022-12-05/7CXXXXXXXX89131670281107_1670281107000_13_1_0/800ff8febfac4c63b86bc18b7df0f042.jpg",
                "startTime": 1670281107000,
                "status": "completed",
                "type": "cloudStorage"
            },
            "infoType": "atomEventV1"
        },
        "time": 1670281107000
    },
    {
        "deviceId": "7CXXXXXXXX0E",
        "deviceType": "atomCamV2",
        "eventId": "db22221df07f4244b53486995c655fb6",
        "eventInfo": {
            "atomEventV1": {
                "endTime": 1670281125000,
                "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281090_1670281090000_13_1_0/8f399fbb27384e07b819bd4997ac0a3f.jpg",
                "startTime": 1670281090000,
                "status": "completed",
                "type": "cloudStorage"
            },
            "infoType": "atomEventV1"
        },
        "time": 1670281090000
    }
...[The following output was omitted because there were so many.]
]

指定されたソラカメ対応カメラで検出されたイベントの一覧を取得する

指定されたソラカメ対応カメラについて、イベントの一覧を取得します。

実行するAPI

指定されたソラカメデバイスで検出されたイベントの一覧を取得します (SoraCam:listSoraCamDeviceEventsForDevice)

CLIコマンド サンプル

※ --device-id の引数は soracom sora-cam devices events list で得たリストの中から対象の deviceId を指定します。

soracom sora-cam devices events list-for-device --device-id 7CXXXXXXXX0E

CLIコマンド実行結果 サンプル（一部抜粋 / 編集済み）

[
    {
        "deviceId": "7CXXXXXXXX0E",
        "deviceType": "atomCamV2",
        "eventId": "ef2222395b8b40b1915da5af100b983e",
        "eventInfo": {
            "atomEventV1": {
                "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281135_1670281135000_13_1_0/311989cf93bf4afa9c282b6a2a682525.jpg",
                "startTime": 1670281135000,
                "status": "recording",
                "type": "cloudStorage"
            },
            "infoType": "atomEventV1"
        },
        "time": 1670281135000
    },
    {
        "deviceId": "7CXXXXXXXX0E",
        "deviceType": "atomCamV2",
        "eventId": "db22221df07f4244b53486995c655fb6",
        "eventInfo": {
            "atomEventV1": {
                "endTime": 1670281125000,
                "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281090_1670281090000_13_1_0/8f399fbb27384e07b819bd4997ac0a3f.jpg",
                "startTime": 1670281090000,
                "status": "completed",
                "type": "cloudStorage"
            },
            "infoType": "atomEventV1"
        },
        "time": 1670281090000
    }
...[The following output was omitted because there were so many.]
]

イベントが検出された瞬間を確認する

最後は実際にイベントAPIを利用して、イベントが検出された瞬間を確認してみます。
イベント一覧から1つイベントを選択して、そのイベントについて動画と静止画を取得していきます。

コマンドサンプルではイベント一覧の最後のイベントを対象としています。
イベントの中には動画が取得できないものがあるので、その場合は別のイベントを選択するなどしてください。

イベント情報から静止画を取得する

イベント情報の中にある time の値はイベントが開始された値となるため、この値を使って静止画を取得するAPIを呼び出します。

CLIコマンド サンプル

※最後の open コマンドは macOS 特有のものであり、Windows(PowerShellやWSL)や、Linuxの場合は画像を開くアプリケーションにて開くようにしてください。

SORA_CAM_EVENT=$(soracom sora-cam devices events list | jq -r '.[-1:]')
echo ${SORA_CAM_EVENT}

IMAGE_TIME=$(echo ${SORA_CAM_EVENT} | jq -r '.[].time' )
echo ${IMAGE_TIME}

soracom sora-cam devices images export --device-id ${DEVICE_ID} --time ${IMAGE_TIME}

EXP_ID=$(soracom sora-cam devices images list-exports --device-id ${DEVICE_ID} | jq -r '.[0].exportId')
echo ${EXP_ID}

soracom sora-cam devices images get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID}

IMAGE_URL=$(soracom sora-cam devices images get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} | jq -r .url)
echo ${IMAGE_URL}

IMAGE_FILE=~/_test/img-test.jpeg
curl -v -L ${IMAGE_URL} -o ${IMAGE_FILE}

open ${IMAGE_FILE}

イベント情報の中にも picture として画像のURLが付与されているので、このURLからイベント開始時の静止画は確認できます。どちらも同じ画像となるため、72時間の出力制限を消費しないイベント情報の画像を利用するのも良い方法かと思います。

picture のURLには有効期限が存在します。有効期限が過ぎて画像が取得できない場合には再度イベント情報を取得しなおしてください。

イベント情報から動画を取得する

イベント情報の中にある startTime / endTime の値はイベントが開始 / 終了の値となるため、この値を使って録画映像をダウンロードするAPIを呼び出します。

2022年12月現時点 でのAPIの制限として1回のダウンロードで指定できる時間の長さは5分以内となっています。コマンドサンプルでは戻り値の  startTime / endTime をそのまま from / to に利用していますが、5分を超えている場合はダウンロードAPIでエラーになるので注意してください。

CLIコマンド サンプル

VIDEO_FROM=$(echo ${SORA_CAM_EVENT} | jq -r '.[].eventInfo.atomEventV1.startTime')
VIDEO_TO=$(echo ${SORA_CAM_EVENT} | jq -r '.[].eventInfo.atomEventV1.endTime' )
echo ${VIDEO_FROM}
echo ${VIDEO_TO}

soracom sora-cam devices videos export --device-id ${DEVICE_ID} --from ${VIDEO_FROM} --to ${VIDEO_TO}

EXP_ID=$(soracom sora-cam devices videos list-exports --device-id ${DEVICE_ID} | jq -r 'sort_by(.requestedTime) | reverse | .[0].exportId')
echo ${EXP_ID}

soracom sora-cam devices videos get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID}

VIDEO_URL=$(soracom sora-cam devices videos get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} | jq -r .url)
echo ${VIDEO_URL}

VIDEO_ZIP_FILE=~/_test/video-test.zip
VIDEO_FILE=~/_test/video-test.mp4

curl -v -L ${VIDEO_URL} -o ${VIDEO_ZIP_FILE}
unzip -p ${VIDEO_ZIP_FILE} > ${VIDEO_FILE}

open ${VIDEO_FILE}

ffmpeg -i ${VIDEO_FILE} -ss 0 -t 1 -r 1 ~/_test/%06d.jpg

open ~/_test

まとめ

今回は「検出されたイベント」を取得できるAPIが追加されたので、APIの紹介と簡単な利用方法を書いてみました。定期的にこのイベントAPIを呼び出して、イベントの一覧を取得することで、イベントを起点としたシステムや仕組みを作れるかと思います。

例えば、部屋の出入り口に設置されているカメラで定期的にイベントを取得し、イベントから静止画を取得しておけば、部屋の入退出リストを画像付きで作ることができます。イベントAPIがPull型となるのでイベントを検知したタイミングで、リアルタイム通知とならない部分はご注意ください。

新しく追加されたAPIを紹介しました。実務に利用する際に少しでも参考になれば嬉しいです。
APIはこれからも引き続き機能追加が行われていく予定となりますので、ぜひ実際に試していただき必要な機能があれば フィードバック をよろしくお願いします。

― ソラコム内田（jet）@uchimanajet7