textflowkit 0.1.3__tar.gz → 0.1.5__tar.gz

{textflowkit-0.1.3 → textflowkit-0.1.5}/.gitattributes

@@ -1,22 +1,22 @@
-# Normalise line endings so a build is the same on every platform.
-#
-# Without this, core.autocrlf rewrites text files on Windows checkout, so a
-# wheel built from a Windows clone differs byte-for-byte from one built on
-# Linux - same code, different bytes - and a published hash cannot be
-# reproduced. Text is stored as LF in the repository and in every build.
-* text=auto eol=lf
-
-# Binary assets must never be rewritten.
-*.png binary
-*.jpg binary
-*.jpeg binary
-*.gif binary
-*.ico binary
-*.pdf binary
-*.docx binary
-*.whl binary
-*.gz binary
-
-# Windows-only scripts keep CRLF.
-*.bat text eol=crlf
-*.cmd text eol=crlf
+# Normalise line endings so a build is the same on every platform.
+#
+# Without this, core.autocrlf rewrites text files on Windows checkout, so a
+# wheel built from a Windows clone differs byte-for-byte from one built on
+# Linux - same code, different bytes - and a published hash cannot be
+# reproduced. Text is stored as LF in the repository and in every build.
+* text=auto eol=lf
+
+# Binary assets must never be rewritten.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.docx binary
+*.whl binary
+*.gz binary
+
+# Windows-only scripts keep CRLF.
+*.bat text eol=crlf
+*.cmd text eol=crlf

{textflowkit-0.1.3 → textflowkit-0.1.5}/.github/workflows/ci.yml

@@ -57,7 +57,8 @@ jobs:
         shell: bash
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,mcp,http]"
+          python -m pip install ./packages/textflowkit-fonts
+          python -m pip install -e ".[dev,mcp,http,export]"
 
       - name: Show ffmpeg version
         shell: bash
@@ -84,6 +85,7 @@ jobs:
         run: |
           python -m pip install "setuptools>=83" "build>=1.2"
           python -m build --wheel
+          python -m build --wheel --outdir dist packages/textflowkit-fonts
       - name: Smoke all three installed entry points
         shell: bash
-        run: python scripts/smoke_installed_wheel.py dist/*.whl
+        run: python scripts/smoke_installed_wheel.py dist/textflowkit-*.whl dist/textflowkit_fonts-*.whl

textflowkit-0.1.5/.github/workflows/publish-pypi.yml

@@ -0,0 +1,114 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.repository == 'scottconverse/textflowkit'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install packaging
+      - name: Verify release tag and package versions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os, tomllib
+          from pathlib import Path
+          from packaging.version import Version
+
+          tag = os.environ['RELEASE_TAG']
+          if not tag.startswith('v'):
+              raise SystemExit('Release tag must start with v')
+          version = str(Version(tag[1:]))
+          if tag != 'v' + version:
+              raise SystemExit('Release tag is not a normalized final version')
+          if Version(version).is_prerelease or Version(version).is_devrelease:
+              raise SystemExit('PyPI release must be a final version')
+          for file in (Path('pyproject.toml'), Path('packages/textflowkit-fonts/pyproject.toml')):
+              declared = tomllib.loads(file.read_text(encoding='utf-8'))['project']['version']
+              if declared != version:
+                  raise SystemExit(f'{file}: {declared} != {version}')
+          PY
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || {
+            echo 'Release tag is not merged into main' >&2
+            exit 1
+          }
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build packaging
+          python -m build --sdist --wheel --outdir dist/main .
+          python -m build --sdist --wheel --outdir dist/fonts packages/textflowkit-fonts
+          python -m pip install twine
+          python -m twine check dist/main/* dist/fonts/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-fonts:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/fonts/
+
+  publish-main:
+    needs: publish-fonts
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/main/
+
+  publish-github-release:
+    needs: publish-main
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - name: Create draft with the exact PyPI distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$RELEASE_TAG" dist/main/* dist/fonts/* \
+            --repo "$GITHUB_REPOSITORY" --verify-tag --draft \
+            --title "$RELEASE_TAG" --generate-notes
+      - name: Publish complete GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release edit "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --draft=false

{textflowkit-0.1.3 → textflowkit-0.1.5}/.gitignore

@@ -17,6 +17,7 @@ work/
 out/
 outputs/
 *.wav
+!src/textflowkit/assets/selftest-speech.wav
 *.mp3
 *.m4a
 *.mp4
@@ -34,4 +35,3 @@ Thumbs.db
 .vscode/
 .idea/
 board/
-

{textflowkit-0.1.3 → textflowkit-0.1.5}/.pre-commit-config.yaml

@@ -15,4 +15,4 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: check-added-large-files
-        args: [--maxkb=1024]
+        args: [--maxkb=1024]

{textflowkit-0.1.3 → textflowkit-0.1.5}/CONTRIBUTING.md

@@ -13,7 +13,8 @@ cd textflowkit
 python -m venv .venv
 # Windows: .venv\Scripts\activate
 # POSIX:   source .venv/bin/activate
-pip install -e ".[dev,mcp,http]"
+pip install ./packages/textflowkit-fonts  # local optional PDF font companion
+pip install -e ".[dev,mcp,http,export]"
 ```
 
 ## Test and lint — the commands CI runs
@@ -60,6 +61,8 @@ mark it so it can be skipped in CI.
 - Add a test for a bug fix. If you cannot, say why in the PR description.
 - Run `ruff check .` and `python -m pytest` before opening the PR.
 - Do not commit media files, transcripts, or scratch output. `work/` is gitignored.
+  The bundled `src/textflowkit/assets/selftest-speech.wav` is an intentional,
+  small synthetic speech fixture; do not replace it with private recordings.
 
 ## Evidence language
 

{textflowkit-0.1.3 → textflowkit-0.1.5}/LEGAL.md

@@ -41,4 +41,4 @@ outside the intended use of this project.
 
 "textflowkit" is an independent open-source project. It is not affiliated with,
 endorsed by, or connected to any other product or organisation using a similar
-name.
+name.

{textflowkit-0.1.3 → textflowkit-0.1.5}/LICENSE

@@ -200,4 +200,4 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-
+

{textflowkit-0.1.3 → textflowkit-0.1.5}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.3
+Version: 0.1.5
 Summary: Cross-platform media transcription toolkit: URL or file in, timestamped transcripts and subtitle files out.
-Project-URL: Homepage, https://github.com/scottconverse/textflowkit
+Project-URL: Homepage, https://www.textflowkit.org/
 Project-URL: Issues, https://github.com/scottconverse/textflowkit/issues
+Project-URL: Source, https://github.com/scottconverse/textflowkit
+Project-URL: Documentation, https://github.com/scottconverse/textflowkit/tree/main/docs
+Project-URL: Changelog, https://github.com/scottconverse/textflowkit/releases
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: speech-to-text,srt,subtitles,transcription,vtt,whisper,yt-dlp
@@ -27,6 +30,7 @@ Requires-Dist: pyannote-audio>=4.0; extra == 'all'
 Requires-Dist: pydantic>=2.7; extra == 'all'
 Requires-Dist: python-docx>=1.1; extra == 'all'
 Requires-Dist: reportlab>=4.0; extra == 'all'
+Requires-Dist: textflowkit-fonts<0.2,>=0.1.5; extra == 'all'
 Requires-Dist: uvicorn>=0.30; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: pypdf>=5; extra == 'dev'
@@ -38,6 +42,7 @@ Requires-Dist: pyannote-audio>=4.0; extra == 'diarize'
 Provides-Extra: export
 Requires-Dist: python-docx>=1.1; extra == 'export'
 Requires-Dist: reportlab>=4.0; extra == 'export'
+Requires-Dist: textflowkit-fonts<0.2,>=0.1.5; extra == 'export'
 Provides-Extra: http
 Requires-Dist: fastapi>=0.115; extra == 'http'
 Requires-Dist: pydantic>=2.7; extra == 'http'
@@ -50,9 +55,14 @@ Description-Content-Type: text/markdown
 
 Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.**
 
-[Project landing page](https://scottconverse.github.io/textflowkit/) ·
+[Project landing page](https://www.textflowkit.org/) ·
+[PyPI package](https://pypi.org/project/textflowkit/) ·
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases)
 
+The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
+Pages. GitHub remains the source and CI host; the website does not run the
+transcription engine.
+
 Paste a URL or point at a file; get timestamped transcripts and subtitle files back.
 Built as a reusable primitive for developers — designed to sit under multiple
 products, AI harnesses, and agents.
@@ -63,12 +73,12 @@ products, AI harnesses, and agents.
 >
 > **This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND**, express or
 > implied, including but not limited to the warranties of MERCHANTABILITY, FITNESS
-> FOR A PARTICULAR PURPOSE, and NONINFRINGEMENT. See [LICENSE](LICENSE) (Apache-2.0,
+> FOR A PARTICULAR PURPOSE, and NONINFRINGEMENT. See [LICENSE](https://github.com/scottconverse/textflowkit/blob/main/LICENSE) (Apache-2.0,
 > §7–8) for the full disclaimer and limitation of liability.
 >
 > **You are responsible for what you transcribe.** textflowkit can fetch media from
 > third-party platforms. Copyright, terms-of-service, and privacy obligations for any
-> media you choose to process are **yours alone**. See [LEGAL.md](LEGAL.md).
+> media you choose to process are **yours alone**. See [LEGAL.md](https://github.com/scottconverse/textflowkit/blob/main/LEGAL.md).
 
 ---
 
@@ -112,40 +122,79 @@ YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rum
 Kick · Zoom · Medal · Loom · Dropbox — plus **direct media URLs and local files**.
 
 All 13 are recognised through `yt-dlp`; only YouTube has an opt-in, maintained
-[live end-to-end smoke](docs/release-checklist.md). It is run on a Windows
+[live end-to-end smoke](https://github.com/scottconverse/textflowkit/blob/main/docs/release-checklist.md). It is run on a Windows
 maintainer machine before a release, not on GitHub-hosted runners or every pull
 request. Local files have also been transcribed live. The other
 12 are not release-verified end to end, and some sources require cookies or
-change their access rules frequently. See [docs/sources.md](docs/sources.md).
+change their access rules frequently. See [docs/sources.md](https://github.com/scottconverse/textflowkit/blob/main/docs/sources.md).
 
 ## Install
 
 Requires **Python ≥ 3.10** and **ffmpeg** on `PATH`.
 
 ```bash
-git clone https://github.com/scottconverse/textflowkit
-cd textflowkit
-pip install -e .
+python -m pip install textflowkit
+textflowkit doctor
 ```
 
-Or install the built wheel from the release page:
+For MCP or the JSON HTTP adapter, install the matching extra:
 
 ```bash
-pip install https://github.com/scottconverse/textflowkit/releases/download/v0.1.3/textflowkit-0.1.3-py3-none-any.whl
+python -m pip install 'textflowkit[mcp]'    # MCP server
+python -m pip install 'textflowkit[http]'   # JSON HTTP API
 ```
 
-Not published to PyPI; the repository and its releases are the distribution path.
-The release page lists each artifact's SHA-256. (Those values are deliberately
-kept out of this file: the README is bundled into the wheel as its description,
-so a hash written here would change the artifact it describes.)
-Optional extras:
+PDF/DOCX export is optional. The default wheel stays small; the `export` extra
+installs `textflowkit-fonts` for offline multilingual PDF rendering:
 
 ```bash
-pip install -e ".[mcp]"    # MCP server adapter
-pip install -e ".[http]"   # HTTP API adapter
-pip install -e ".[dev]"    # tests + linter
+python -m pip install 'textflowkit[export]'
+```
+
+## Python API
+
+The same pipeline used by the CLI and adapters is available to Python callers:
+
+```python
+from textflowkit import transcribe
+
+result = transcribe(
+    "meeting.mp4",            # also accepts supported URLs
+    model="small",
+    formats=["json", "srt", "txt"],
+    output_dir="transcripts", # omit to return the transcript without writing files
+)
+print(result.transcript.text)
+print(result.transcript.duration)  # full media duration in seconds
+print(result.outputs)              # pathlib.Path objects for written files
+for segment in result.transcript.segments:
+    print(segment.start, segment.end, segment.speaker, segment.text)
+    for word in segment.words:
+        print("  ", word.start, word.end, word.text)
 ```
 
+`transcribe()` returns `TranscribeResult` with a canonical `Transcript` and
+written output paths. `Transcript.to_dict()` / `.to_json()` preserve segment and
+word timing; older transcript JSON without `words` remains readable. Pass
+`input_root=` to confine local input paths for untrusted callers. See
+[the install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+for ffmpeg and Windows ROCm setup.
+
+MCP and HTTP transcript reads omit word timings by default to keep responses
+small; set `include_words=true` on a JSON read to receive them. Saved files,
+Python results, and durable job records still retain the source-language words,
+including when segment text has been translated.
+
+**AMD ROCm on native Windows:** do not use the generic command in an environment
+with a working ROCm PyTorch install. Ordinary dependency resolution can replace
+that torch build. Follow the [ROCm install notes](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+to preserve it.
+
+The same version's wheel and source archive are also on the
+[GitHub release page](https://github.com/scottconverse/textflowkit/releases/latest).
+The release lists their SHA-256 hashes. For editable source development, see
+[CONTRIBUTING.md](https://github.com/scottconverse/textflowkit/blob/main/CONTRIBUTING.md).
+
 ## Usage
 
 ```bash
@@ -187,7 +236,7 @@ textflowkit export ./transcript.json --format vtt
 ## Use as an MCP server
 
 ```bash
-pip install -e ".[mcp]"
+python -m pip install 'textflowkit[mcp]'
 textflowkit-mcp                                  # stdio
 textflowkit-mcp --transport http --port 8766     # Streamable HTTP
 ```
@@ -214,12 +263,12 @@ These checks are not end-to-end transcription runs driven by each harness:
 There is also a protocol test that launches the server as a real subprocess and
 speaks newline-delimited JSON-RPC over stdio, so the entry point, framing, and
 version negotiation are covered on every CI run (`tests/test_stdio_protocol.py`).
-See [docs/adapters.md](docs/adapters.md) for per-harness configuration.
+See [docs/adapters.md](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md) for per-harness configuration.
 
 ## Use as an HTTP API
 
 ```bash
-pip install -e ".[http]"
+python -m pip install 'textflowkit[http]'
 textflowkit-http --port 8767
 ```
 
@@ -227,7 +276,7 @@ Submit a job, poll it, fetch the transcript. Developer mode is unauthenticated
 and defaults to localhost. The opt-in JSON HTTP production profile requires a
 Bearer token, explicit roots, durable SQLite jobs, and request/rate/media/output
 limits; URL input additionally requires an SSRF-filtering egress proxy. See
-[adapter deployment details](docs/adapters.md#developer-mode-and-production-profile).
+[adapter deployment details](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md#developer-mode-and-production-profile).
 
 ## Durable, bounded, cancellable
 
@@ -237,7 +286,7 @@ TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; Whisper saturates a GPU alone
 ```
 
 `cancel_job` stops a queued job immediately, or a running job at its next stage
-boundary. See [docs/adapters.md](docs/adapters.md).
+boundary. See [docs/adapters.md](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md).
 
 ## Long jobs never block
 
@@ -248,19 +297,19 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.3 release.** Core, CLI, MCP, and HTTP have automated
+**v0.1.4 release.** Core, CLI, MCP, and HTTP have automated
 coverage; Windows-native ROCm and a dated local Windows YouTube run were verified.
 The GitHub-hosted YouTube attempt was blocked by a bot challenge, so hosted
 live transcription is not verified.
 This does not imply that all 13 platforms or every harness workflow has been
-tested end to end. See [docs/roadmap.md](docs/roadmap.md).
+tested end to end. See [docs/roadmap.md](https://github.com/scottconverse/textflowkit/blob/main/docs/roadmap.md).
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE). Includes an explicit patent grant and a
+Apache-2.0 — see [LICENSE](https://github.com/scottconverse/textflowkit/blob/main/LICENSE). Includes an explicit patent grant and a
 limitation of liability.
 
 ## Contributing
 
-Issues and PRs welcome. Please read [LEGAL.md](LEGAL.md) before adding a source
+Issues and PRs welcome. Please read [LEGAL.md](https://github.com/scottconverse/textflowkit/blob/main/LEGAL.md) before adding a source
 adapter.

{textflowkit-0.1.3 → textflowkit-0.1.5}/README.md

@@ -2,9 +2,14 @@
 
 Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.**
 
-[Project landing page](https://scottconverse.github.io/textflowkit/) ·
+[Project landing page](https://www.textflowkit.org/) ·
+[PyPI package](https://pypi.org/project/textflowkit/) ·
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases)
 
+The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
+Pages. GitHub remains the source and CI host; the website does not run the
+transcription engine.
+
 Paste a URL or point at a file; get timestamped transcripts and subtitle files back.
 Built as a reusable primitive for developers — designed to sit under multiple
 products, AI harnesses, and agents.
@@ -15,12 +20,12 @@ products, AI harnesses, and agents.
 >
 > **This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND**, express or
 > implied, including but not limited to the warranties of MERCHANTABILITY, FITNESS
-> FOR A PARTICULAR PURPOSE, and NONINFRINGEMENT. See [LICENSE](LICENSE) (Apache-2.0,
+> FOR A PARTICULAR PURPOSE, and NONINFRINGEMENT. See [LICENSE](https://github.com/scottconverse/textflowkit/blob/main/LICENSE) (Apache-2.0,
 > §7–8) for the full disclaimer and limitation of liability.
 >
 > **You are responsible for what you transcribe.** textflowkit can fetch media from
 > third-party platforms. Copyright, terms-of-service, and privacy obligations for any
-> media you choose to process are **yours alone**. See [LEGAL.md](LEGAL.md).
+> media you choose to process are **yours alone**. See [LEGAL.md](https://github.com/scottconverse/textflowkit/blob/main/LEGAL.md).
 
 ---
 
@@ -64,40 +69,79 @@ YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rum
 Kick · Zoom · Medal · Loom · Dropbox — plus **direct media URLs and local files**.
 
 All 13 are recognised through `yt-dlp`; only YouTube has an opt-in, maintained
-[live end-to-end smoke](docs/release-checklist.md). It is run on a Windows
+[live end-to-end smoke](https://github.com/scottconverse/textflowkit/blob/main/docs/release-checklist.md). It is run on a Windows
 maintainer machine before a release, not on GitHub-hosted runners or every pull
 request. Local files have also been transcribed live. The other
 12 are not release-verified end to end, and some sources require cookies or
-change their access rules frequently. See [docs/sources.md](docs/sources.md).
+change their access rules frequently. See [docs/sources.md](https://github.com/scottconverse/textflowkit/blob/main/docs/sources.md).
 
 ## Install
 
 Requires **Python ≥ 3.10** and **ffmpeg** on `PATH`.
 
 ```bash
-git clone https://github.com/scottconverse/textflowkit
-cd textflowkit
-pip install -e .
+python -m pip install textflowkit
+textflowkit doctor
 ```
 
-Or install the built wheel from the release page:
+For MCP or the JSON HTTP adapter, install the matching extra:
 
 ```bash
-pip install https://github.com/scottconverse/textflowkit/releases/download/v0.1.3/textflowkit-0.1.3-py3-none-any.whl
+python -m pip install 'textflowkit[mcp]'    # MCP server
+python -m pip install 'textflowkit[http]'   # JSON HTTP API
 ```
 
-Not published to PyPI; the repository and its releases are the distribution path.
-The release page lists each artifact's SHA-256. (Those values are deliberately
-kept out of this file: the README is bundled into the wheel as its description,
-so a hash written here would change the artifact it describes.)
-Optional extras:
+PDF/DOCX export is optional. The default wheel stays small; the `export` extra
+installs `textflowkit-fonts` for offline multilingual PDF rendering:
 
 ```bash
-pip install -e ".[mcp]"    # MCP server adapter
-pip install -e ".[http]"   # HTTP API adapter
-pip install -e ".[dev]"    # tests + linter
+python -m pip install 'textflowkit[export]'
+```
+
+## Python API
+
+The same pipeline used by the CLI and adapters is available to Python callers:
+
+```python
+from textflowkit import transcribe
+
+result = transcribe(
+    "meeting.mp4",            # also accepts supported URLs
+    model="small",
+    formats=["json", "srt", "txt"],
+    output_dir="transcripts", # omit to return the transcript without writing files
+)
+print(result.transcript.text)
+print(result.transcript.duration)  # full media duration in seconds
+print(result.outputs)              # pathlib.Path objects for written files
+for segment in result.transcript.segments:
+    print(segment.start, segment.end, segment.speaker, segment.text)
+    for word in segment.words:
+        print("  ", word.start, word.end, word.text)
 ```
 
+`transcribe()` returns `TranscribeResult` with a canonical `Transcript` and
+written output paths. `Transcript.to_dict()` / `.to_json()` preserve segment and
+word timing; older transcript JSON without `words` remains readable. Pass
+`input_root=` to confine local input paths for untrusted callers. See
+[the install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+for ffmpeg and Windows ROCm setup.
+
+MCP and HTTP transcript reads omit word timings by default to keep responses
+small; set `include_words=true` on a JSON read to receive them. Saved files,
+Python results, and durable job records still retain the source-language words,
+including when segment text has been translated.
+
+**AMD ROCm on native Windows:** do not use the generic command in an environment
+with a working ROCm PyTorch install. Ordinary dependency resolution can replace
+that torch build. Follow the [ROCm install notes](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+to preserve it.
+
+The same version's wheel and source archive are also on the
+[GitHub release page](https://github.com/scottconverse/textflowkit/releases/latest).
+The release lists their SHA-256 hashes. For editable source development, see
+[CONTRIBUTING.md](https://github.com/scottconverse/textflowkit/blob/main/CONTRIBUTING.md).
+
 ## Usage
 
 ```bash
@@ -139,7 +183,7 @@ textflowkit export ./transcript.json --format vtt
 ## Use as an MCP server
 
 ```bash
-pip install -e ".[mcp]"
+python -m pip install 'textflowkit[mcp]'
 textflowkit-mcp                                  # stdio
 textflowkit-mcp --transport http --port 8766     # Streamable HTTP
 ```
@@ -166,12 +210,12 @@ These checks are not end-to-end transcription runs driven by each harness:
 There is also a protocol test that launches the server as a real subprocess and
 speaks newline-delimited JSON-RPC over stdio, so the entry point, framing, and
 version negotiation are covered on every CI run (`tests/test_stdio_protocol.py`).
-See [docs/adapters.md](docs/adapters.md) for per-harness configuration.
+See [docs/adapters.md](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md) for per-harness configuration.
 
 ## Use as an HTTP API
 
 ```bash
-pip install -e ".[http]"
+python -m pip install 'textflowkit[http]'
 textflowkit-http --port 8767
 ```
 
@@ -179,7 +223,7 @@ Submit a job, poll it, fetch the transcript. Developer mode is unauthenticated
 and defaults to localhost. The opt-in JSON HTTP production profile requires a
 Bearer token, explicit roots, durable SQLite jobs, and request/rate/media/output
 limits; URL input additionally requires an SSRF-filtering egress proxy. See
-[adapter deployment details](docs/adapters.md#developer-mode-and-production-profile).
+[adapter deployment details](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md#developer-mode-and-production-profile).
 
 ## Durable, bounded, cancellable
 
@@ -189,7 +233,7 @@ TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; Whisper saturates a GPU alone
 ```
 
 `cancel_job` stops a queued job immediately, or a running job at its next stage
-boundary. See [docs/adapters.md](docs/adapters.md).
+boundary. See [docs/adapters.md](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md).
 
 ## Long jobs never block
 
@@ -200,19 +244,19 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.3 release.** Core, CLI, MCP, and HTTP have automated
+**v0.1.4 release.** Core, CLI, MCP, and HTTP have automated
 coverage; Windows-native ROCm and a dated local Windows YouTube run were verified.
 The GitHub-hosted YouTube attempt was blocked by a bot challenge, so hosted
 live transcription is not verified.
 This does not imply that all 13 platforms or every harness workflow has been
-tested end to end. See [docs/roadmap.md](docs/roadmap.md).
+tested end to end. See [docs/roadmap.md](https://github.com/scottconverse/textflowkit/blob/main/docs/roadmap.md).
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE). Includes an explicit patent grant and a
+Apache-2.0 — see [LICENSE](https://github.com/scottconverse/textflowkit/blob/main/LICENSE). Includes an explicit patent grant and a
 limitation of liability.
 
 ## Contributing
 
-Issues and PRs welcome. Please read [LEGAL.md](LEGAL.md) before adding a source
+Issues and PRs welcome. Please read [LEGAL.md](https://github.com/scottconverse/textflowkit/blob/main/LEGAL.md) before adding a source
 adapter.

{textflowkit-0.1.3 → textflowkit-0.1.5}/SECURITY.md

@@ -13,7 +13,7 @@ you expected.
 
 | Version | Security-fix policy |
 |---|---|
-| Latest published release tag (currently `v0.1.3`) | Receives fixes through the next patch release |
+| Latest published release tag (see [GitHub releases](https://github.com/scottconverse/textflowkit/releases)) | Receives fixes through the next patch release |
 | Earlier release tags, including earlier `0.1.x` tags | No backports |
 | Unreleased `main` commits | Development only; not a supported release |