Metadata-Version: 2.1
Name: django-transcribe
Version: 0.10.0
Summary: Core Django app for Transcribe
Author-email: BYU Library IT <byulibraryit@byu.edu>
Project-URL: Source, https://gitlab.com/byuhbll/lib/python/django-transcribe
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: Django <5.3,>=3.2
Requires-Dist: django-model-utils
Requires-Dist: lxml

# `django-transcribe`

## Transcribe Texts, Audio, and Video

Django-Transcribe helps you crowdsource the work of transcription. A typical workflow looks like this:

- Create a new project and upload media (page scans, audio clips, or video clips).
- Visitors grab a task (usually a scanned page) from the project and transcribe it.
- After two visitors have transcribed the same task, a reviewer looks at a diff of the two transcriptions, choosing the best options and making any final changes.
- The reviewer can highlight and tag things like people, places, and dates.
- When all tasks in a project are finished it can be downloaded as plain text, HTML, or an XML document

![Transcribe screenshot](docs/images/review-and-tagging.png)

## Installing `django-transcribe`
*Updated for Python 3.14, Django 5.2, and uv.*

`django-transcribe` is a Django app designed to run within a Django project. You can install it in an existing project or create a new Django project.
After installation, you can customize `django-transcribe` by overriding templates and making other changes at the project level.

### 1. Install uv
If uv isn't already installed, follow the [official installation instructions](https://docs.astral.sh/uv/getting-started/installation/).

On Linux or macOS:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Create a Django Project
Create a new project directory and initialize it with uv.
```bash
uv init your_project_name
cd your_project_name
```

Make sure that the project uses Python 3.14:
```bash
uv python pin 3.14
```

Install Django 5.2 and django-transcribe:
```bash
uv add "django~=5.2" django-transcribe
```

Create the Django project in the current directory:
```bash
uv run django-admin startproject your_project_name .
```

> [!WARNING]
> Do not name your project `transcribe`, as this will cause naming conflicts.

### 3. Configure the installed apps
Add `transcribe` to `INSTALLED_APPS` in `your_project_name/settings.py`:
```python
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'transcribe',
]
```

### 4. Configure URLs
Update `your_project_name/urls.py` to include the `django-transcribe` URLs:

```python
from django.contrib import admin
from django.urls import include, path
# Specifically this one
from transcribe import urls as transcribe_urls
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include(transcribe_urls)),
    path('accounts/', include('django.contrib.auth.urls')),
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```

### 5. Configure Media Storage
Create a media directory. This is where your media files, like scanned images, will be uploaded:
```bash
mkdir media
```

At the bottom of `your_project_name/settings.py` add:
```python
MEDIA_ROOT = './media/'
MEDIA_URL = '/media/'
```
These settings will allow your media files to be served up in your development environment, but for production you will need to configure your web server to serve files from the media directory.

### 6. Initialize the Database
Run database migrations and create a superuser:
```bash
uv run python manage.py migrate
uv run python manage.py createsuperuser
```

### 7. Start the Development Server
Start up Django using uv:
```bash
uv run python manage.py runserver
```
Open http://127.0.0.1:8000/ in your browser.
You should now be able to log in using the superuser credentials you created.

### 8. Create a New Transcribe Project
Once the application is running:
1. Click the menu in the upper-right corner and select **Projects**.
2. Click **Create a New Project**.
3. Complete the form, including selecting media to upload.
4. Direct users to your site to begin transcribing.

> [!WARNING]
> Commit both `pyproject.toml` and `uv.lock` to version control to maintain reproducible environments.

## Configuration and Customization
In the `your_project_name/settings.py` file you can configure some options:
```python
TRANSCRIBE_SETTINGS = {
    'support_email': 'transcribe_support@domain.com',
    'from_email': 'no_reply@domain.com',
    'task_expire_days': 14,  # how many days until an unfinished task expires
}
```
Override template files as you would in any Django project.

## Contributing to this project
### Project development setup
Follow these steps to set up your development environment:
1. Clone the repository and enter its directory:
   ```bash
   git clone https://gitlab.com/byuhbll/lib/python/django-transcribe
   cd django-transcribe
   ```
2. From within the newly created repository directory, run `uv sync`. This will automatically create a development environment.
3. Run `uv run pre-commit install`. These pre-commit hook checks must pass before committing.
4. Install Node 24 (or greater) from [here](https://nodejs.org/en/download) and run `npm install` from the root directory. Node is required for the package's frontend development tooling.
5. Virtual environment activation is optional. To activate it, run `source .venv/bin/activate`. Otherwise, run commands with `uv run <command>`.

### Testing in this project
- Run `uv run tox` on the command line, and the unit tests and linting should run for all supported Python versions.
- To run specific tox versions, look at the tox environment configuration in `pyproject.toml` to see which versions are available. Then run `uv run tox -e <version>`
	- Example: `uv run tox -e py314-django52`

### Testing the Package within an App
In the app's `pyproject.toml`, keep `django-transcribe` in the existing `[project]` dependencies list and add a separate `[tool.uv.sources]` section. Merge these entries into existing sections rather than duplicating section headers:
```toml
[project]
dependencies = [
    "django-transcribe",
    # Keep your other dependencies here.
]

[tool.uv.sources]
django-transcribe = { path = "editable_packages/django-transcribe", editable = true }
```
The path is relative to the app's project directory. The published package must support the Python and Django versions you choose; verify compatibility before using it in a new project.

Next, to keep tests in editable packages out of the app's test run, add `norecursedirs` to the existing `[tool.pytest.ini_options]` section. Replace `project.settings` with the app's Django settings module:
```toml
[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "project.settings"
python_files = ["test_*.py"]
norecursedirs = ["editable_packages"]  # Exclude tests in all editable packages
```

> [!INFO]
> Keep `django-transcribe` in the dependency list for normal development. The initial container-build workaround below is a temporary exception.

Last, ensure that the library is mounted in the running container. Go into your `docker-compose.yml` in `.devcontainer` and add the following line to **volumes:**
```yml
    volumes:
      - "..:/code"
      - "/path/to/package:/code/editable_packages/django-transcribe" # Add this
```
Replace `/path/to/package` with the absolute path to the package on the host. When the container starts, the bind mount makes the source code available, allowing you to edit the package while working with the app that uses the package.

#### Development Gotchas
When using `django-transcribe` as an editable package inside a dev container, you may run into issues with `uv sync` during the initial build. This happens because the package isn't available inside the container until it's been built and the directory has been mounted.

To get around this:
1. Comment out `django-transcribe` in the `dependencies` section of `pyproject.toml`.
2. Build the container as normal.
3. Once inside the container, uncomment the dependency.
4. Run `uv sync` to install the package.

This should allow uv to find the editable package and install it correctly. If the build still fails, check whether the Dockerfile is trying to install the package before its source code is available.
