---
title: Function Format Document
tags: Speaker
---
# Function Format Document
所有僅限音箱內使用的 function
~~因為系統架構的問題，所有的 function 需要有 return，這個 return value 對於大部分的功能來說應該會是要丟到文字轉~~
~~> For features that need to be called by 「文字理解」, please specify the variable needed to call your feature function.~~
### Requirements
1. Arguments type & name
2. 缺少某個 Arguments 的話，需要執行的動作（重新詢問使用者）
3. 簡單說明 function 作用
4. Descripition 可以中文
5. Arguments default value
### 命名格式
class: 首字母大寫駝峰式
function: 底線
variable: 駝峰
### return 格式
`(class_name, function_name, (arg...))`
class_name, function_name: 要呼叫的 class 和 function name，無則該欄為 None
(arg): 被呼叫的 function 所需參數，無則該欄為 None
## 文字理解
class:Extract
### Extract.main(input_str)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str | **string** | - | 原始輸入 |
從語音辨識接收輸入字串，並回傳所要呼叫的 function 及其參數
<!--
### text2func(input_str)
| Name | Arguments type | Default value | Description |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| input_str | **string** | - | to see what user want to do |
從語音辨識接收輸入字串，回傳即將呼叫的 function名稱及對應到的關鍵字
### isPhoneNumber(str)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| str | **string** | - | the target |
判斷字串是否為電話號碼（`r'\d(-\d)*'`）
### para_extract(input_str, func_key)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str | **string** | - | 原始輸入 |
|func_key|**list**|-|[0]：即將呼叫的 function 名稱<br>[1]：對應到的關鍵字|
根據即將要呼叫的 function 從原始字串中提取參數
### _trans(input_str)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str | **string** | - | the target |
將 input_str 的數字字串轉為數字
### set_time(newtime)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| newtime | **list** | - | [year, month, hour, minute] |
根據 newtime 所示回傳指定時間字串
### target_time(input_str, mode)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str | **string** | - | the target |
|mode|**int**|-|0 for calender related<br>1 for weather related|
根據輸入字串提取所想表達的時間及剩餘字串 -->
## 語音辨識
### SpeechToText.voice_to_text()
No parameter.
| Name | Arguments type | Default value | Description |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| return | **string** | NULL | 語音辨識結果 |
## 文字轉語音
### TextToSpeech.text_to_voice(sentence)
| Name | Arguments type | Default value | Description |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| sentence | **string** | NULL | 要轉成語音的句子 |
No return value.
## 即時翻譯功能
### Translate.translate(fromLanguage, toLanguage)
| Name | Arguments type | Default value | Description |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| fromLanguage | **string** | 'zh-TW' | 原語言 |
| toLanguage | **string** | 'en' | 新語言 |
* fromLanguage, toLanguage只支援'zh-TW'（中文）, 'en'（英文）, 'fr'（法文）
No return value.
## 天氣功能
class: Weather
### weather_forecast(time, place)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| time | **datetime** | datetime.now() | 使用者想要查詢天氣預報的時間 |
| place | **string** | 使用者設定之位置 <br> or <br> 透過 IP 尋找音箱位置 | 使用者想要查詢天氣預報的地區 <br> (台灣縣市 or 全球都市) |
從文字理解接收使用者想要查詢的天氣預報之時間以及地點資訊(地點為台灣縣市或全球都市)，透過連結外部api查詢該地區該時間的天氣預報資訊，若查無此地點或是欲查詢的時間超過一週，則回傳「查詢不到」至文字轉語音
#### response
| Name | Value |
| -------------- | ---------- |
| situation | **string** |
回傳天氣狀況
## 音樂功能
class: MusicStreaming
### play_music(target)
| Name | Arguments type | Default value | Description |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| target | **string** | - | 使用者欲播放音樂之關鍵字 <br> 歌名 or 歌手+歌名 |
從文字理解接收使用者想要播放的音樂關鍵字（歌名 or 歌手+歌名），透過連結外部api查詢該歌曲並播放
No return value.
### pause_music()
暫停現在正在播放的音樂
No return value.
### continue_music()
繼續播放已暫停的音樂
No return value.
### stop_music()
停止現在正在播放或暫停中的音樂
No return value.
### now_playing()
回傳現在正在播放的歌手以及歌曲名稱
#### response
| Name | Value |
| ------------------ | ----------- |
| nowMusic | **string** |
### repeat_playing()
重複播放音樂
No return value.
### return_playing_status()
回傳現在音樂的狀態。
若音樂正在播放，全域變數isPlaying = T、isPause = F、isStop = F。
若音樂狀態是暫停中，全域變數isPause = T、isPlaying = F、isStop = F。
若音樂已停止，全域變數isStop = T、isPlaying = F、isPause = F。
#### response
| Name | Value |
| ------------------ | ----------- |
| isPlaying | **Boolean** |
| isPause | **Boolean** |
| isStop | **Boolean** |
<!--
## 雙聲道功能
### close_dual_speaker()
取消雙聲道模式，並斷開兩音箱的藍芽
### connect_dual_speaker(speakerNickname)
| Name | Arguments type | Default value | Description |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| speakerNickname | **string** | - | 使用者的第要連接的音箱代稱 |
### play_music_dual_speaker(music)
| Name | Arguments type | Default value | Description |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| music | **vlc instance** | - | vlc(播放模組) 的 instance |
-->
## 藍芽音箱
### Bluetooth.open_bluetooth()
會開啟藍芽並可以被偵測
### Bluetooth.close_bluetooth()
斷開連接並關閉藍芽
### Bluetooth.get_bluetooth_status()
查詢藍牙連接狀態
#### response
| Name | Value |
| ------------------ | ----------- |
| isConnect | **Boolean** |
| connectedDeviceMAC | **string** |
### Bluetooth.pause_bluetooth_playing()
若有正在進行的音樂會傳送訊號到手機暫停
## 問題回答
###
class: QuestionAnswering
@HsuanYu 抱歉，那個是class的名稱
從網路搜尋取得使用者問題查詢到的結果、答案，最後回傳可能的答案。
如果查詢不到合理的答案，將回傳「無相關搜尋結果」。
如果設定為將結果回傳給使用者，將呼叫相關 API 。
### google_search( query_str )
透過 Google 進行網路查詢。
| Name | Arguments type | Default value | Description |
| ------ | :------------: | ------------- |:----------------:|
| query_str | **string** | - |使用者欲查詢之問題字串|
| return | **list** | - | 網頁搜尋結果 |
### get_answer( results )
將查到的結果頁面進行處理，取得想要的部分，輸出答案以及相關資料。
| Name | Arguments type | Default value | Description |
| ------ | :------------: | ------------- |:----------------:|
| result | **list** | - | 網頁搜尋結果 |
| return | **string** | - |答案字串/相關查詢結果|
## Calendar
class: Calendar
### add_calendar(date, start_time, end_time, event)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| start_time | **string** | - | 活動開始時間 |
| end_time | **string** | start_time 後一小時 | 活動結束時間 |
| event | **string** | - | 活動名稱 |
### add_calendar_week(day, start_time, end_time, event)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| day | **unsigned int** | - | 重複週幾 |
| start_time | **string** | - | 活動開始時間 |
| end_time | **string** | start_time 後一小時 | 活動結束時間 |
| event | **string** | - | 活動名稱 |
重複每週 day 直到當年年底
### add_calendar_day(start_time, end_time, event)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| start_time | **string** | - | 活動開始時間 |
| end_time | **string** | start_time 後一小時 | 活動結束時間 |
| event | **string** | - | 活動名稱 |
重複每天直到當年年底
### read_calendar(date)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| date | **string** | date.today() | 活動日期 |
查詢於 date 開始且結束的行程
### read_calendar_next()
查詢下一個行程
## Make calls
class: Call
### make_call(number)
| Name | Arguments type | Default value | Description |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| number | **string** | - | 使用者想要撥打的號碼 |
## 系統音量控制
### Volume.louder_system_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int | 5 | 上升多少音量 |
### Volume.quieter_system_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int | 5 | 下降多少音量 |
### Volume.set_system_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int | 未修改前的值 | 音量設定值 |
### Volume.get_system_volume()
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ---------------- |
| return | unsigned int | 當前值 | 回傳當前系統音量 |
## 音樂音量控制
### Volume.louder_music_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ------------ |
| value | unsigned int | 5 | 上升多少音量 |
### Volume.quieter_music_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ------------ |
| value | unsigned int | 5 | 下降多少音量 |
### Volume.set_music_volume(value)
| Name | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int | 未修改前的值 | 音量設定值 |
### Volume.get_music_volume()
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ---------------- |
| return | unsigned int | 當前值 | 回傳當前系統音量 |
## 傳輸搜尋結果至手機
### deliver_to_cellphone(resultURL,keyWord,userId)
class:Delivery
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ---------------- |
| resultURL | string | - | 問題回答找到的網址 |
| keyWord | string | - | 用來搜尋的關鍵字 |
| userId | string | "" | 要傳過去的userId，因為伺服器不會知道是哪個使用者傳的，如果沒有綁定的話就傳空字串 |
| return | int | - | 回傳傳輸結果 |
0：網頁與LINE皆傳送失敗、1：網頁傳送成功，LINE傳送失敗、2：網頁傳送失敗，LINE傳送成功、3：網頁與LINE皆傳送成功
## 使用音箱紀錄備忘錄
### memorandum()
class:Memorandum
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ---------------- |
| return | | - | |
## 倒計時
### Countdown.set_timer(hours, minute, second)
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ------------ |
| hours | int | | |
| minute | int | | |
| second | int | | |
| return | boolean | | 輸入是否合法 |
## 世界時鐘
### WorldTime.get_time_at_place(place)
class: WorldTime
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ----------- |
| place | string | 使用者所在地 | |
| return | string | XX:XX(24小時制) | |
## 鬧鐘
### Alarm.set_alarm(day, hour, minute)
class: Alarm
| Name | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ----------- |
| day | int(1-7) | 今天或明天（最近抵達時間） | |
| hours | int | | |
| minute | int | | |
| return | None | | |
## 重置
### listen_reset_button()
class: FactoryReset
Should be a daemon thread
No return value
### factory_reset()
class: FactoryReset
This function can only be accessed via GPIO input
No return value
Sign in with Wallet
Connect another wallet