---
# System prepended metadata

title: "CodeWithHarry - OpenAI Whisper Tutorial + Audio to Text Translator Website Project \U0001F525"
tags: [ASR, AI]

---

# 影片主題與目標

* 介紹 OpenAI Whisper API 的概念與使用方式
* 示範 Whisper API 的實際運作流程
* 在 Replit 上實作一個簡單的網頁介面，完成「上傳音訊 → 轉錄／翻譯 → 回傳結果」

# Replit 與 Bounties 介紹
![image](https://hackmd.io/_uploads/H1q1GO8xZx.png)
![image](https://hackmd.io/_uploads/rJzxMu8l-e.png)

* Replit Bounties 提供各種專案任務，可完成後獲得報酬（cycles）
* cycles 可換成真實貨幣
* 透過 Bounties 可以學習實作、接觸專案並與其他開發者互動

# 在 Replit 建立 Whisper 專案
![image](https://hackmd.io/_uploads/HkT7GuLlWx.png)

* 前往 replit.com 登入帳號
* 建立新的 Repl，選擇 Python 方案
* 專案命名為與 Whisper 相關的名稱（例如 openai-whisper）
* 使用 Replit 的原因是環境簡單、瀏覽器即可開發，不需在本機安裝一堆工具

# 取得與管理 OpenAI API Key
![image](https://hackmd.io/_uploads/BJ3rf_Ix-e.png)

* 登入 OpenAI 帳號，建立新的 API key，名稱可設為 whisper
* 產生 secret key 後複製並妥善保存，不可公開
* 在 Replit 的 Secrets 中新增環境變數（例如 OPENAI_KEY），方便程式透過 os.environ 讀取
* 目前已取消免費試用，使用 OpenAI API 需先儲值（約 4–5 美元）
* Whisper 本地模型可不使用 API key，但使用雲端 Whisper API、GPT-3、GPT-4 等就需要

# Whisper 功能與特性說明
![image](https://hackmd.io/_uploads/HJXvMdIxZe.png)

* Whisper 是 OpenAI 的自動語音辨識（ASR）與翻譯模型
* 能將音訊轉成文字（transcription）
* 能將一種語言的語音翻譯成另一種語言（translation）
* 能處理混合語言內容，判斷哪些詞應維持英文、哪些轉成目標語言
* 模型訓練資料龐大，因此文字較自然，不像一般機器翻譯那種「翻譯腔」

# 準備錄音檔並上傳到 Replit
![image](https://hackmd.io/_uploads/BJutzu8l-g.png)

* 使用 Windows 內建錄音程式錄製一段測試語音（自我介紹＋ Whisper 說明）
* 錄完後在檔案總管中尋找錄音檔（例如 Recording 2）
* 將檔名改為 audio.mp3 或類似名稱
* 在 Replit 專案中將 audio.mp3 上傳到專案根目錄，待程式讀取

# 安裝 Whisper 與相關套件

* 根據 GitHub 上 openai/whisper 專案的說明，使用 pip 安裝 whisper
* 若執行時缺少依賴（例如 numpy），再個別 pip 安裝
* Whisper 需要 ffmpeg 處理音訊檔
* 在 Replit 的 Packages 中搜尋並安裝 ffmpeg 套件
* 也可透過 ffmpeg.bin 並修改 replit.nix，使 ffmpeg 指令可直接在 Shell 中使用

# 使用本機 Whisper 模型（不用 API Key）

* 透過 whisper 套件直接載入模型並進行推論
* 程式大致流程為：import whisper、載入 base 模型、讀取 audio.mp3、呼叫 model.transcribe、印出文字結果
* 這種方式僅使用 Replit 或本機的硬體，不會呼叫 OpenAI 雲端
* 實際轉錄結果大致正確，但在細節（例如人名）可能有小錯

# 使用 OpenAI Whisper API（雲端模式）

* 安裝 openai 套件，使用官方 API 客戶端呼叫 whisper-1 模型
* 在程式中 import openai 與 os，透過 os.getenv 讀取存於 Secrets 的 API key
* 將 key 設定為 openai.api_key
* 開啟 audio.mp3 作為 audio file，呼叫 Whisper API 進行 transcribe
* 取得 transcript 後印出文字內容
* 此方式使用的是 OpenAI 的雲端硬體，會消耗帳戶額度
* 實測顯示雲端 Whisper API 的轉錄比本機 base 模型更精準，尤其在人名等細節上

# Whisper 翻譯示範（Hindi → English）

* 再錄製一段主要使用印地文的句子，內容表達類似「今天要教你使用 OpenAI」
* 將錄音檔改名為 Hindi.mp3 並上傳至 Replit
* 修改程式讓 audio file 指向 Hindi.mp3
* 呼叫 Whisper API 的翻譯功能，輸出英文文字
* 實際結果可將印地文內容自然翻譯成英文，並忠實保留原本語意

# 建立 Flask 網頁介面上傳音訊

* 新增 Flask 應用檔（例如 main_flask.py，後來改名為 main.py）
* 使用 Ghostwriter 生成最簡 Flask 範例：index 頁面提供上傳音訊檔的表單
* 在程式中設定 UPLOAD_FOLDER 指向 static 目錄
* 定義根路由 "/" 同時處理 GET 與 POST
* GET 請求時回傳簡單 HTML，內含音訊檔上傳表單
* POST 請求時從 request.files 取得上傳檔案，儲存到 static 目錄
* 在 Replit 啟動 Flask 時設定 host 為 0.0.0.0 以便從瀏覽器預覽
* 新增 static 資料夾，避免「找不到 static 目錄」錯誤

# Flask 與 Whisper 串接邏輯

* 上傳檔案成功後不再 redirect 到檔案網址，而是直接對該檔做轉錄或翻譯
* 於 Flask 的 POST 處理程式中載入剛存好的音訊檔路徑
* 使用先前示範的 Whisper API 呼叫程式碼進行 transcribe 或 translate
* 取得 transcript 結果後以 jsonify 包裝成 JSON 回傳
* 整體效果為：使用者透過網頁上傳音訊檔，伺服器呼叫 Whisper API 處理後，直接回傳文字結果（可再由前端顯示）


---

# 使用 Whisper 轉錄與基本網頁介面

* 上傳 `Hindi.mp3` 後，後端呼叫 OpenAI 語音模型成功取得英文逐字稿「Hi, my name is Hari and today I will teach you how to use OpenAI」
* 目前網頁介面包含檔案上傳與文字顯示，但作者認為 UI 可再優化以提升使用體驗

# 嘗試直接在語音翻譯端點指定目標語言失敗

* 目標是將輸出從預設英文改為其他語言（如孟加拉文）
* 在程式中加入 `target_language = "bn"` 之類設定後輸出仍為英文
* 改用 `language="bn"` 觸發「value is not a valid enumeration member，只允許 en」錯誤
* 結論是該語音翻譯端點無法自由指定任意語言參數達成多語翻譯

# 改用 GPT-4 Chat Completion 進行文字翻譯
![image](https://hackmd.io/_uploads/ryoGXuIg-l.png)

* 先用 Whisper 取得文字 transcript，再將文字交給 GPT-4 做翻譯
* Chat Completion 設定 `messages`：`system` 說明「請將輸入翻成某語言」，`user` 放入 transcript 文字
* 修正錯誤包含：補上 `messages = [...]`、將 `role` 改為字串、把整個 transcript 物件改成 `transcript.text`
* 修正後 GPT-4 能輸出孟加拉文翻譯，驗證「語音轉文字 + GPT-4 翻譯」流程可行

# 新增語言輸入欄位並串接到後端

* 在 Flask 後端使用 `language = request.form["language"]` 取得表單輸入的語言
* system 訊息中目標語言改為使用 `language` 變數，而非寫死為孟加拉文
* 回應改為 `render_template("index.html")`，並建立 `templates/index.html` 作為主要頁面
* Ghostwriter 幫忙改寫 HTML，在表單中加入 `name="language"` 的文字輸入欄位

# 前端 UI 與 CSS 調整

* 原本 `body` 使用 `display: flex` 搭配 `justify-content: center` 造成頁面垂直置中與導覽列位置問題
* 移除 `body` 的過度置中設定，並在通用選擇器 `*` 設定 `margin: 0`、`padding: 0`
* 在 `nav a` 中設定白色文字與移除底線，讓導覽列更清楚
* 重新啟動後，輸入 `French` 並上傳 `Hindi.mp3`，成功獲得法文翻譯結果

# 使用 Replit 部署 Flask 應用

* 在本地開發測試完成後停止開發中的伺服器
* 於 Replit 的 Deployments 選擇 Reserved VM，設定約 0.5 vCPU 和 2GB RAM
* 在部署設定中加入環境變數（例如 `OPENAI_API_KEY`）供後端存取 OpenAI
* 執行指令設定為 `python3 main.py`，部署完成後取得公開 URL 可直接訪問應用程式

# 在本機安裝 openai-whisper 並用 CLI 執行
![image](https://hackmd.io/_uploads/B13_muIlZg.png)
![image](https://hackmd.io/_uploads/B1qqm_UgZx.png)

* 透過 `pip install -U openai-whisper` 安裝 Whisper，而不一定需要手動下載 GitHub 專案
* 安裝後可使用 `whisper` 指令與 `whisper --help` 查看可用參數
* 可指定音檔與語言，例如對 `japanese.wav` 使用 `--language Japanese` 或使用 `--task translate`
* 可選擇不同模型大小（tiny、base、small、medium、large）以取得不同精度與效能平衡

# 使用 WhisperJAX 線上轉錄與產生時間戳文字
![image](https://hackmd.io/_uploads/ry4a7_IgZx.png)

* 介紹 Hugging Face 上的 WhisperJAX 空間，可透過瀏覽器進行語音轉文字
* 支援三種輸入來源：麥克風錄音、上傳音檔、貼上 YouTube 影片 URL
* 可勾選 translate 與 return timestamps，取得翻譯文字與對應時間戳
* 複製帶時間戳的文字後，可再交由其他工具或程式轉換成 SRT 等字幕格式使用

# 部署結果與 API Key 提醒

* Replit 部署完成後，使用部署 URL 測試上傳 `Hindi.mp3` 並輸入語言，整體流程可正常運作
* 示範中使用的 API Key 之後會從帳號刪除，實際使用時需自行在專案中設定個人 API Key
* 透過自行持有的 API Key，即可在同一套流程中使用 Whisper 轉錄與 GPT-4 翻譯多語音訊內容



---
# Terminology
* Whisper API（Whisper API）：OpenAI 提供的語音轉文字與翻譯雲端介面
* 應用程式介面（Application Programming Interface, API）：讓程式彼此呼叫功能與交換資料的規範
* Replit 平台（Replit Platform）：一個在瀏覽器就能寫程式、執行與部署的線上開發環境
* Repl 專案（Repl Project）：在 Replit 裡的一個程式專案或執行環境單位
* Replit 賞金任務（Replit Bounties）：在 Replit 上承接別人的專案來完成並賺取報酬的系統
* Cycles 虛擬貨幣（Cycles Currency）：Replit 上用來支付資源與兌換價值的虛擬代幣
* 秘密金鑰（Secret Key）：連線到雲端服務時用來驗證身分的私密字串
* API 金鑰管理（API Key Management）：安全保存、讀取與更新 API 金鑰的做法
* 環境變數（Environment Variable）：儲存在系統環境裡的設定值，程式可用來讀取機密或配置
* OS 模組（os Module）：Python 內建，用來操作檔案系統與環境變數的程式庫
* 套件管理工具（Package Manager, pip）：用來安裝與更新 Python 外部程式庫的工具
* GitHub 儲存庫（GitHub Repository）：託管與分享程式碼、版本紀錄與文件的專案空間
* Python 使用範例（Python Usage Example）：官方文件給出的 Python 程式碼示範寫法
* 自動語音辨識系統（Automatic Speech Recognition System, ASR）：自動把語音內容轉成文字的系統
* 音訊轉錄（Audio Transcription）：把錄好的音檔內容完整寫成文字的過程
* 語音翻譯（Speech Translation）：一邊聽語音一邊把內容轉成另一種語言文字的技術
* 語音錄製工具（Voice Recorder）：用來錄下麥克風聲音並存成檔案的程式
* MP3 音訊格式（MP3 Audio Format）：常見的有損壓縮音訊檔案格式
* Shell 終端機（Shell Terminal）：輸入指令並看到執行結果的文字操作介面
* 依賴套件（Dependencies）：程式執行時必須先安裝好的外部程式庫或工具
* FFmpeg 工具（FFmpeg Tool）：用來轉檔、剪輯與處理音訊與影像的命令列工具
* Whisper 基礎模型（Whisper Base Model）：Whisper 提供的中等大小、精度與速度平衡的預訓練模型
* 模型下載（Model Download）：第一次使用時從網路抓取模型檔案到本地機器的動作
* 本地執行（Local Execution）：在自己電腦或 Replit 容器上直接跑模型，而不是叫雲端 API
* 雲端硬體（Cloud Hardware）：由服務商提供的遠端伺服器與 GPU 計算資源
* OpenAI 託管模型（OpenAI Hosted Model）：部署在 OpenAI 伺服器，由 API 呼叫使用的模型
* 付費帳號（Paid Account）：已經儲值或綁定付款方式，可以正式使用付費 API 的帳號
* 試用額度（Free Trial Credit）：官方送的有限金額，可以先免費測試服務的點數
* 自動英譯功能（Automatic English Translation）：自動把其他語言的語音內容翻成英文文字的功能
* 語言混合句子（Code-switching Sentence）：一段話中混合使用多種語言的說話方式
* Flask 網頁框架（Flask Web Framework）：用 Python 快速建立簡單網站與 API 的輕量級框架
* 路由（Route）：網站裡對應特定網址路徑所要執行的程式函式設定
* HTTP 方法（HTTP Method）：像 GET、POST 等，用來表示這個網路請求要做什麼操作的標記
* GET 請求（GET Request）：向伺服器索取資料、不帶有檔案上傳的一種請求方式
* POST 請求（POST Request）：向伺服器送出表單資料或檔案內容的一種請求方式
* 檔案上傳（File Upload）：把本機檔案透過表單送到伺服器儲存或處理的動作
* 上傳資料夾（Upload Folder）：伺服器上用來存放使用者上傳檔案的指定目錄
* 靜態資源資料夾（Static Folder）：用來存放圖片、音訊、CSS 等不需程式計算就能直接提供的檔案
* HTML 表單（HTML Form）：網頁上讓使用者輸入文字或選擇檔案並送出的區塊
* 重新導向（Redirect）：伺服器回應時要求瀏覽器自動跳轉到另一個網址的行為
* JSON 回應（JSON Response）：伺服器用 JSON 格式傳回結構化資料給前端的方式
* jsonify 函式（jsonify Function）：Flask 中把 Python 資料轉成 JSON 回應物件的工具函式
* 主機位址 0.0.0.0（Host 0.0.0.0）：代表伺服器監聽所有網路介面的特別位址設定
* 連接埠 5000（Port 5000）：Flask 預設使用的網路連線通道號碼
* Web 伺服器（Web Server）：接收 HTTP 請求並回傳網頁或資料給使用者的程式
* 前後端互動（Frontend-Backend Interaction）：瀏覽器畫面與伺服器程式之間互相傳送資料的流程
* 語音應用網頁介面（Voice App Web Interface）：讓使用者上傳錄音並看到轉錄結果的網頁畫面
* 錄音檔轉文字服務（Audio-to-Text Service）：使用者上傳錄音檔後，系統自動輸出對應文字的線上服務
* 錯誤訊息除錯（Debugging Error Messages）：閱讀並分析程式錯誤訊息來找出問題原因的過程
* Ghostwriter 程式碼產生工具（Ghostwriter Code Generator）：Replit 裡可根據文字描述自動產生程式碼的輔助工具
* 語音轉文字（Speech-to-Text）：把說話的聲音自動變成可以看的文字的技術
* 文字轉語音（Text-to-Speech）：把打出來的文字念成聲音讓人聽的技術
* 轉錄（Transcription）：把一整段錄音內容完整寫成文字的過程
* 翻譯（Translation）：把一種語言的內容換成另一種語言但意思不變
* 目標語言（Target Language）：想要翻成的那一種語言
* API 金鑰（API Key）：用來證明「你是你」的秘密密碼，給電腦服務認得你
* 環境變數（Environment Variable）：藏在系統裡的設定資料，程式可以讀但不會寫在程式碼上
* 後端伺服器（Backend Server）：在電腦後面幫忙處理資料、算東西、不直接給人看的程式
* 前端介面（Frontend Interface）：網頁上讓使用者看到、點按和輸入的畫面
* Web 介面（Web Interface）：用瀏覽器打開就能操作的網頁應用程式
* 部署（Deployment）：把寫好的程式放到線上的電腦上，讓大家都可以使用
* 保留虛擬機（Reserved VM）：租來一台在雲端的「假電腦」，專門跑你的程式
* CPU 核心（CPU Core）：負責算數學、跑程式的大腦單位，核心越多可以同時做越多事
* 記憶體（RAM）：程式暫時放資料的地方，關機就會清空
* HTTP 請求（HTTP Request）：瀏覽器對伺服器說「請給我資料」或「幫我做事」的訊息
* JSON 回應（JSON Response）：用 JSON 格式包好的資料，讓前端跟後端容易交換資訊
* 端點（Endpoint）：伺服器提供服務的特定網址，就像服務窗口的門牌號碼
* 回呼函式（Callback Function）：等事情做完後再被叫回來執行的函式
* 例外處理（Exception Handling）：程式出錯時，不讓程式整個掛掉，而是好好處理錯誤的方法
* 無效請求錯誤（Invalid Request Error）：送給伺服器的資料不合規定時得到的錯誤訊息
* 文字稿（Transcript）：把錄音完整寫下來的文字內容
* 時間戳記（Timestamp）：記錄某一句話是從幾分幾秒開始的小時間標記
* SRT 字幕檔（SRT Subtitle File）：用來存影片字幕和時間點的文字檔格式
* 指令列工具（Command-line Tool）：在黑底白字的視窗裡靠打指令操作的工具
* 開源程式庫（Open-source Library）：大家都可以免費看、用、改的程式碼集合
* GitHub 儲存庫（GitHub Repository）：放專案程式碼的線上資料夾，還能記錄歷史版本
* Python 腳本（Python Script）：用 Python 寫的一個檔案，裡面放著要執行的程式碼
* 函式呼叫（Function Call）：在程式裡請某個函式幫忙做一件事
* 參數（Parameter）：呼叫函式時，順便帶進去告訴它要用什麼資料
* 物件（Object）：把很多相關資料和功能打包起來的一個東西
* 清單（List）：可以依順序存放很多資料的一條「資料陣列」
* 模型（Model）：電腦學習後得到的「腦袋」，可以用來預測或產生東西
* 語言模型（Language Model）：專門用來理解和產生文字的人工智慧模型
* GPT-4 模型（GPT-4 Model）：OpenAI 做的強大語言模型，可以聊天、翻譯和寫程式
* Whisper 模型（Whisper Model）：OpenAI 做的語音轉文字模型，聽懂很多語言
* Replit 平台（Replit Platform）：一個可以在瀏覽器裡寫程式、執行和部署的網站
* Ghostwriter 外掛（Ghostwriter Extension）：Replit 裡幫你自動補程式碼、改程式的 AI 助手
* HTML 樣板（HTML Template）：有固定架構的網頁骨架，可以重複套用來產生頁面
* CSS 樣式（CSS Styles）：決定網頁長相的規則，像顏色、大小、排列方式
* 響應式設計（Responsive Design）：讓同一個網頁在手機、平板、電腦上都好看的設計方式
* 導覽列（Navbar）：網頁上方或側邊用來放選單連結的那條列
* 表單欄位（Form Field）：讓使用者輸入文字、選項或檔案的小格子
* 檔案上傳（File Upload）：把你電腦裡的檔案送到伺服器上的動作
* request.files 物件（request.files Object）：後端在程式裡用來讀使用者上傳檔案的地方
* request.form 物件（request.form Object）：後端在程式裡用來讀表單文字欄位的地方
* render_template 函式（render_template Function）：後端用來把 HTML 樣板送給瀏覽器顯示的函式
* JSON 序列化（JSON Serialization）：把資料轉成 JSON 字串，方便在網路上傳來傳去
* Web 伺服器框架（Web Framework）：幫你快速做網站後端的工具箱和規則集合
* 虛擬環境（Virtual Environment）：把專案需要的套件關在一個小房間裡，不跟其他專案互相干擾
* 命令（Command）：在終端機或指令列裡打的一行文字，用來叫電腦做某件事
