{"id":28506805,"url":"https://github.com/temporalio/build-audiobook-go","last_synced_at":"2025-08-16T15:18:02.424Z","repository":{"id":251089568,"uuid":"836358825","full_name":"temporalio/build-audiobook-go","owner":"temporalio","description":"Build your own audiobooks from text files","archived":false,"fork":false,"pushed_at":"2025-07-02T18:10:06.000Z","size":111,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-05T04:39:06.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/temporalio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-31T17:17:31.000Z","updated_at":"2025-07-02T18:10:09.000Z","dependencies_parsed_at":"2025-07-05T15:46:00.769Z","dependency_job_id":null,"html_url":"https://github.com/temporalio/build-audiobook-go","commit_stats":null,"previous_names":["temporalio/build-audiobook-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/temporalio/build-audiobook-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Fbuild-audiobook-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Fbuild-audiobook-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Fbuild-audiobook-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Fbuild-audiobook-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/temporalio","download_url":"https://codeload.github.com/temporalio/build-audiobook-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/temporalio%2Fbuild-audiobook-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270729289,"owners_count":24635397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T20:06:27.114Z","updated_at":"2025-08-16T15:18:02.401Z","avatar_url":"https://github.com/temporalio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Build Your Own Audiobooks\n\nOpenAI offers so many opportunities to use the power of large models to create amazing results.\nThis project uses [OpenAI's text-to-speech (TTS) API](https://platform.openai.com/docs/guides/text-to-speech) to convert text into audiobooks.\n\nAdding Temporal to this process ensures a smooth and robust audiobook creation experience.\nTemporal's open-source solutions add hassle-free fault mitigation to your projects.\nBy integrating Temporal with OpenAI, you can take full advantage of OpenAI's many TTS features without worrying about errors.\n\nOpenAI provides [top-quality voices](https://platform.openai.com/docs/guides/text-to-speech/voice-options) and extensive [language support](https://platform.openai.com/docs/guides/text-to-speech/supported-output-formats), allowing you to choose the perfect tone and rhythm for your audio files.\nTogether, these two technologies help you focus on creating great content.\n\n**_This project is part of a tutorial._** Follow along by reading the [Build Your Own Audiobooks guide](https://learn.temporal.io/tutorials/go/audiobook/) at [Temporal's learn site](https://learn.temporal.io/tutorials).\n\n**This tutorial is written to be run on a single system, with a single Worker, using the local file system.**\n**This is a tutorial project and its implementation is suited for personal and hobbyist use.**\n**In production, you wouldn't read or write from a single database file or system.**\n**This approach isn't durable so you wouldn't develop durable software with them.**\n\n**Durable execution refers to maintaining state and progress even in the face of failures, crashes, or server outages.**\n**For durable execution, you must be able to rebuild progress state and store information somewhere more reliable.**\n**If you expand on this project, consider a API-based Cloud storage solution.**\n\n## Prerequisites\n\nBefore starting this project, make sure you have the following:\n\n- An active OpenAI API developer account and your bearer token.\n- Familiarity with the Go programming language.\n- The Temporal CLI tool and development server installed on your system.\n  Refer to [Getting Started with Go and Temporal](https://learn.temporal.io/getting_started/go/dev_environment/) for detailed setup instructions.\n\n## Setup\n\nFollow these steps to begin converting text to audio.\n\n### Run the Development Server\n\nMake sure the Temporal development server is running and using a persistent store.\nInterrupted work can be picked up and continued without repeating steps, even if you experience server interruptions:\n\n```sh\ntemporal server start-dev \\\n    --db-filename /path/to/your/temporal.db\n```\n\nOnce running, connect to the [Temporal Web UI](http://localhost:8233/) and verify that the server is working.\n\n\n### Instantiate Your Bearer Token\n\nCreate an environment variable called OPEN_AI_BEARER_TOKEN to configure your OpenAI credentials.\nIf you set this value using a shell script, make sure to `source` the script so the variable carries over past the script execution.\nThe environment variable must be set in the same shell where you'll run your application.\n\n### Run the application (Worker)\n\n```\ngo run worker/main.go\n```\n\nIf the Worker can't fetch a bearer token from the shell environment, it will loudly fail at launch.\nThis early check prevents you from running jobs and waiting to find out that you forgot to set the bearer token until you're well into the Workflow process.\n\nNow that the Worker is running, you can submit jobs for text-to-speech processing.\n\n## Submit narration jobs\n\nIn a new terminal window, use the Temporal CLI tool to build audio from text files.\nUse the Workflow `execute` subcommand to watch the execution in real time from the command line:\n\n```\ntemporal workflow execute \\\n    --type TTSWorkflow \\\n    --task-queue tts-task-queue \\\n    --input '\"/path/to/your/text-file.txt\"' \\\n    --workflow-id \"tristam-shandy-tts\"\n```\n\n* **type**: The name of this text-to-speech Workflow is `TTSWorkflow`.\n* **task-queue**: This Worker polls the \"tts-task-queue\" Task Queue.\n* **input**: Pass a quoted JSON string with a /path/to/your/input/text-file.\n* **workflow-id**: Set a descriptive name for your Workflow Id.\n  This makes it easier to track your Workflow Execution in the Web UI.\n \nPlease note:\n\n* The identifier you set won't affect the input text file or the output audio file names.\n* Use full paths as the Worker is not given context for relative path resolution.\n* Sample files appear in the `text-samples` folder.\n\n### The output file\n\nYour output is collected in a system-provided temporary file.\n\nAfter, your generated MP3 audio is moved into the same folder as your input text file.\nIt uses the same name replacing the `txt` extension with `mp3`.\nIf an output file already exists, the project versions it to prevent name collisions.\n\nThe Workflow returns a string, the /path/to/your/output/audio-file.\nCheck the Web UI Input and Results section after the Workflow completes.\nThe results path is also displayed as part of the CLI's `workflow execute` command output and in the Worker logs.\n\n### Cautions and notes\n\n- Do not modify your input or output files while the Workflow is running.\n- The Workflow fails if you don't pass a valid text file named with a `txt` extension.\n\n### Peeking at the process\n\nThis project includes a Query to check progress during long processes.\nRun it in a separate terminal window or tab:\n\n```\ntemporal workflow query \\\n    --type fetchMessage \\\n    --workflow-id YourWorkflowId\n```\n\n### Validate your audio output\n\nThe open source [checkmate](https://github.com/Sjord/checkmate) app lets you validate your generated MP3 file for errors.\n\n```\n$ mpck -v audio.mp3\n\nSUMMARY: audio.mp3\n    version                       MPEG v2.0\n    layer                         3\n    bitrate                       160000 bps\n    samplerate                    24000 Hz\n    frames                        23723\n    time                          9:29.352\n    unidentified                  0 b (0%)\n    stereo                        yes\n    size                          11120 KiB\n    ID3V1                         no\n    ID3V2                         no\n    APEV1                         no\n    APEV2                         no\n    last frame                    \n        offset                    11386560 b (0xadbec0)\n        length                    480\n    errors                        none\n    result                        Ok\n```\n\n### Converting chapter files into a book\n\nConsider submitting each chapter as a separate Workflow.\nThis allows you to quality check each file and ensure it \"reads\" the way you want.\nAfter generating all your chapters and front material, back material, and other book elements, you can combine them together.\n\nUse [`ffmpeg`](https://ffmpeg.org) to combine audio files.\n\n1. Create a text file listing the files, for example:\n\n```text\nfile 'title_sequence.mp3'\nfile 'introduction.mp3'\nfile 'chapter1.mp3'\nfile 'chapter2.mp3'\nfile 'chapter3.mp3'\n...\n``` \n\n2. Perform the concatenation:\n\n```\nffmpeg -f concat -safe 0 -i chapters-list.txt -c copy fullbook.mp3\n```\n\n3. (optional) `ffmpeg` allows you to convert your audio to other formats.\nFor example:\n\n```\nffmpeg -i fullbook.mp3 fullbook.m4a\n```\n\n## Project Structure\n\n```sh\n.\n├── LICENSE\n├── README.md\n├── TTSActivities.go\n├── TTSWorkflow.go\n├── go.mod\n├── go.sum\n├── text-samples\n│   ├── austen.txt\n│   └── doyle.txt\n└── worker\n    └── main.go\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemporalio%2Fbuild-audiobook-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftemporalio%2Fbuild-audiobook-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemporalio%2Fbuild-audiobook-go/lists"}