Feature: share the Word heading font, metadata paragraph, and file response

[branch1337]

Description

Summary, notes, and the chat on one recording each download a Word file. Each route builds that file by pasting the same two blocks. download_summary_word (src/api/recordings.py:367-471), download_chat_word (src/api/recordings.py:477-609), and download_notes_word (src/api/recordings.py:615-718) each define a nested add_unicode_paragraph (src/api/recordings.py:400-410, src/api/recordings.py:515-525, src/api/recordings.py:647-657) and each set Arial plus the east-Asia font on the heading when the title is not ASCII (src/api/recordings.py:388-397, src/api/recordings.py:505-512, src/api/recordings.py:636-644). Each then saves a BytesIO, calls send_file with as_attachment=False, and sets Content-Disposition, including the RFC 2231 branch (src/api/recordings.py:428-466, src/api/recordings.py:565-604, src/api/recordings.py:675-713).

The markdown body is already one function, process_markdown_to_docx (src/services/document.py:11-281). Its font helper, ensure_unicode_font, is nested inside that function (src/services/document.py:33-47) and is not callable from the three routes, so the routes carry a second copy of the same Arial and east-Asia assignment. A later Word download has no function to call for the heading, the metadata paragraph, or the file response. The workaround is to paste those blocks again.

Each route also builds ascii_filename and never reads it (src/api/recordings.py:438-441, src/api/recordings.py:575-578, src/api/recordings.py:685-688). The header uses filename when that string is ASCII, and encode_rfc2231 when it is not.

Affected Version

v0.10.19-alpha

Requested Feature

Summary, notes, and chat downloads keep the files they return today. The heading font, the metadata paragraph font, and the Word file response exist once, in src/services/document.py, and the three routes call them.

add_unicode_heading(doc, text, level) adds a heading and, when text is not ASCII, sets every run to Arial with east-Asia Arial. add_unicode_paragraph(doc, text) does the same for one paragraph. Both use one ensure_unicode_font(run, text). process_markdown_to_docx calls that same function for its runs. Inline code keeps its own Consolas east-Asia font (src/services/document.py:66-79). A link run still goes through ensure_unicode_font (src/services/document.py:81-87).

docx_attachment_response(doc, filename, fallback_filename) saves the document and returns the response. send_file is called with as_attachment=False and the Word media type. An ASCII filename produces attachment; filename="<filename>". A non-ASCII filename produces attachment; filename*=<encode_rfc2231(filename, charset='utf-8')> and the same info log the routes write today. If that encoding raises, the header is attachment; filename="<fallback_filename>" and the error is logged. The unused ascii_filename value is not computed.

What stays on each route is the access check, the empty-body refusal, the heading string, the metadata lines, the filename built from the title, and the markdown source. The chat route still loops the posted messages itself, including the reasoning paragraph. There is no new environment variable and no change to the transcript download or the on-disk markdown export.

Proposed Implementation

process_markdown_to_docx (src/services/document.py:11) is the function that already sees every Word body. The font and the file response belong next to it.

Before, each Word route carries its own heading font, its own metadata paragraph, and its own file response. The markdown body is the only shared call, and ensure_unicode_font is nested inside it, so the routes cannot call that font helper.

flowchart TD
    summaryBefore[download_summary_word]
    notesBefore[download_notes_word]
    chatBefore["download_chat_word, message loop inside"]
    summaryFont[heading font and add_unicode_paragraph]
    notesFont[heading font and add_unicode_paragraph]
    chatFont[heading font and add_unicode_paragraph]
    summaryFile["BytesIO, send_file, Content-Disposition"]
    notesFile["BytesIO, send_file, Content-Disposition"]
    chatFile["BytesIO, send_file, Content-Disposition"]
    markdownBefore[process_markdown_to_docx]
    nestedFont["ensure_unicode_font, nested and not callable"]

    summaryBefore --> summaryFont
    summaryBefore --> summaryFile
    summaryBefore --> markdownBefore
    notesBefore --> notesFont
    notesBefore --> notesFile
    notesBefore --> markdownBefore
    chatBefore --> chatFont
    chatBefore --> chatFile
    chatBefore --> markdownBefore
    markdownBefore --> nestedFont

Loading

After, the three routes call the shared helpers. The chat message loop stays inside download_chat_word. Transcript text, the on-disk markdown export, and HTML rendering do not call them.

flowchart TD
    summary[download_summary_word]
    notes[download_notes_word]
    chat["download_chat_word, message loop stays here"]
    heading[add_unicode_heading]
    paragraph[add_unicode_paragraph]
    font[ensure_unicode_font]
    markdown[process_markdown_to_docx]
    codeRun["add_code_run, Consolas"]
    response[docx_attachment_response]
    transcript[download_transcript_with_template]
    exporter[export_recording]
    html[md_to_html]

    summary --> heading
    summary --> paragraph
    summary --> markdown
    summary --> response
    notes --> heading
    notes --> paragraph
    notes --> markdown
    notes --> response
    chat --> heading
    chat --> paragraph
    chat --> markdown
    chat --> response
    heading --> font
    paragraph --> font
    markdown --> font
    markdown --> codeRun

Loading

transcript, exporter, and html have no arrow. They keep their own output. Extend the import at src/api/recordings.py:53 so the three routes take add_unicode_heading, add_unicode_paragraph, and docx_attachment_response from src.services.document. Do not add those names to src/services/__init__.py:30, and do not add them to the unused import at src/app.py:560. After the three call sites are gone, delete from email.utils import encode_rfc2231 at src/api/recordings.py:23. quote at src/api/recordings.py:24 stays, because the transcript download still uses it (src/api/recordings.py:353).

def ensure_unicode_font(run, text):
    """Arial and the east-Asia font when text is not ASCII. ASCII leaves the run alone."""
    try:
        text.encode('ascii')
    except UnicodeEncodeError:
        from docx.oxml.ns import qn
        run.font.name = 'Arial'
        run._element.rPr.rFonts.set(qn('w:eastAsia'), 'Arial')
    return run


def add_unicode_heading(doc, text, level):
    """A heading, with the font the three Word downloads set on a non-ASCII title."""
    heading = doc.add_heading(text, level)
    try:
        text.encode('ascii')
    except UnicodeEncodeError:
        for run in heading.runs:
            ensure_unicode_font(run, text)
    return heading


def add_unicode_paragraph(doc, text):
    """A paragraph, with the font the three nested helpers set on non-ASCII metadata."""
    paragraph = doc.add_paragraph(text)
    try:
        text.encode('ascii')
    except UnicodeEncodeError:
        for run in paragraph.runs:
            ensure_unicode_font(run, text)
    return paragraph


def docx_attachment_response(doc, filename, fallback_filename):
    """The Word response summary, notes, and chat already return."""
    from email.utils import encode_rfc2231
    from io import BytesIO
    from flask import current_app, send_file

    doc_stream = BytesIO()
    doc.save(doc_stream)
    doc_stream.seek(0)
    response = send_file(
        doc_stream,
        as_attachment=False,
        mimetype='application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    )
    try:
        filename.encode('ascii')
        response.headers['Content-Disposition'] = f'attachment; filename="{filename}"'
    except UnicodeEncodeError:
        try:
            encoded_value = encode_rfc2231(filename, charset='utf-8')
            header_value = f'attachment; filename*={encoded_value}'
            current_app.logger.info(
                f"DEBUG CHINESE FILENAME (RFC2231): Original='{filename}', Header='{header_value}'"
            )
            response.headers['Content-Disposition'] = header_value
        except Exception as e:
            current_app.logger.error(f"RFC2231 encoding failed: {e}, using fallback")
            response.headers['Content-Disposition'] = f'attachment; filename="{fallback_filename}"'
    return response

Delete the nested ensure_unicode_font at src/services/document.py:33-47. The calls inside process_markdown_to_docx (src/services/document.py:57-61, src/services/document.py:87, src/services/document.py:109, src/services/document.py:123) use the module function. Leave add_code_run (src/services/document.py:66-79) on Consolas.

In each route, delete the nested helper, the heading font block, the BytesIO save, and the header block. Keep the title string, the metadata, the blank line before the body, and the filename regex. download_summary_word (src/api/recordings.py:382-467) becomes:

doc = Document()
title_text = f'Summary: {recording.title or "Untitled Recording"}'
add_unicode_heading(doc, title_text, 0)
from src.utils.timezones import to_user_local
add_unicode_paragraph(doc, f'Uploaded: {to_user_local(recording.created_at, recording.owner).strftime("%Y-%m-%d %H:%M")}')
if recording.meeting_date:
    add_unicode_paragraph(doc, f'Recording Date: {to_user_local(recording.meeting_date, recording.owner).strftime("%Y-%m-%d")}')
if recording.participants:
    add_unicode_paragraph(doc, f'Participants: {recording.participants}')
visible_tags = recording.get_visible_tags(current_user)
if visible_tags:
    tags_str = ', '.join([tag.name for tag in visible_tags])
    add_unicode_paragraph(doc, f'Tags: {tags_str}')
doc.add_paragraph('')
process_markdown_to_docx(doc, recording.summary)
safe_title = re.sub(r'[<>:"/\\|?*]', '', recording.title or 'Untitled')
safe_title = re.sub(r'[-\s]+', '-', safe_title).strip('-')
filename = f'summary-{safe_title}.docx' if safe_title else f'summary-recording-{recording_id}.docx'
return docx_attachment_response(doc, filename, f'download-{recording_id}.docx')

download_notes_word (src/api/recordings.py:630-714) is the same shape with Notes:, recording.notes, the notes- filename, and the same fallback download-<id>.docx. download_chat_word (src/api/recordings.py:498-605) uses Chat Conversation:, the two metadata lines at src/api/recordings.py:528-531, the message loop at src/api/recordings.py:533-563 unchanged, the chat- filename, and the same fallback. The from docx.shared import Inches and from io import BytesIO lines inside the three functions go away. from docx import Document stays inside the try, so a failure while building the file is still word_document_failed.

Leave download_transcript_with_template (src/api/recordings.py:206-360) on its text or markdown body and its filename* header (src/api/recordings.py:346-354). Leave export_recording (src/file_exporter.py:705-720) writing markdown to disk. Leave md_to_html (src/utils/markdown.py:94-100) converting markdown to HTML. Do not merge summary and notes into one route. Do not move the chat message loop.

Tests already pin the summary and chat responses: test_download_summary_empty_400, test_download_summary_present_returns_docx, test_download_chat_empty_messages_400, test_download_chat_missing_key_400, and test_download_chat_with_messages_returns_docx in tests/test_cov_recordings_read.py. test_download_summary_present_returns_docx (tests/test_cov_recordings_read.py:1704-1720) and test_download_chat_with_messages_returns_docx (tests/test_cov_recordings_read.py:1755-1776) return 500 if as_attachment becomes True. Notes has no such test. test_download_endpoints_reject_non_owner (tests/test_cov_recordings_download_authz.py:44-79) only checks that the owner is not answered with 403. The recording it builds has a summary and no notes, so the owner request to /download/notes is the empty-notes 400 and never builds a file.

Add notes=None to make_recording (tests/test_cov_recordings_read.py:158-176) and pass it to Recording. The default keeps every current caller on a row with no notes. Then add test_download_notes_empty_400 and test_download_notes_present_returns_docx next to the summary tests. The empty case uses the default, GET /recording/<id>/download/notes, expects 400, and expects notes in error. The present case passes notes="## Heading\n\nSome **notes** content.", expects 200, a content type containing wordprocessingml, and a non-empty body. no_notes is the English string No notes available for this recording (static/locales/en.json:3363).

Add tests/test_word_download_helpers.py. It imports app from src.app the way tests/test_cov_recordings_read.py does, and calls the helpers inside app.test_request_context() because send_file needs a request. Build documents with docx.Document.

• test_unicode_paragraph_sets_east_asia_font: add_unicode_paragraph with 预算 sets the run font name to Arial and w:eastAsia to Arial.
• test_ascii_paragraph_leaves_east_asia_unset: add_unicode_paragraph with Tags: Planning does not set w:eastAsia.
• test_unicode_heading_sets_east_asia_font: add_unicode_heading with Summary: 预算 at level 0 sets Arial and w:eastAsia Arial.
• test_markdown_paragraph_uses_shared_font: process_markdown_to_docx with 预算 sets w:eastAsia to Arial on that run.
• test_inline_code_keeps_consolas: process_markdown_to_docx with `预算` sets w:eastAsia to Consolas on the code run.
• test_ascii_filename_disposition: docx_attachment_response(doc, 'summary-weekly.docx', 'download-4.docx') sets Content-Disposition to attachment; filename="summary-weekly.docx".
• test_non_ascii_filename_uses_rfc2231: filename summary-预算.docx sets the header to attachment; filename*= plus encode_rfc2231(filename, charset='utf-8').
• test_rfc2231_failure_uses_fallback: patching encode_rfc2231 to raise sets attachment; filename="download-4.docx".

Run from speakr.git:

python -m pytest tests/test_word_download_helpers.py tests/test_cov_recordings_read.py::test_download_summary_empty_400 tests/test_cov_recordings_read.py::test_download_summary_present_returns_docx tests/test_cov_recordings_read.py::test_download_notes_empty_400 tests/test_cov_recordings_read.py::test_download_notes_present_returns_docx tests/test_cov_recordings_read.py::test_download_chat_empty_messages_400 tests/test_cov_recordings_read.py::test_download_chat_missing_key_400 tests/test_cov_recordings_read.py::test_download_chat_with_messages_returns_docx tests/test_cov_recordings_download_authz.py::test_download_endpoints_reject_non_owner

Expected Behavior

• GET /recording/<id>/download/summary with a summary still returns 200 and a Word body. With no summary it still returns 400 and no_summary. The heading is still Summary: <title>, and the metadata lines are still uploaded time, recording date, participants, and visible tags.
• GET /recording/<id>/download/notes with notes returns 200 and a Word body. With no notes it returns 400 and no_notes. The heading is still Notes: <title>.
• POST /recording/<id>/download/chat with messages still returns 200. An empty list and a missing messages key still return 400. The file still has Chat Conversation: <title>, Recording Date, Chat Export Date, You and Assistant, the reasoning paragraph when thinking is set on an assistant turn, and a blank paragraph between turns.
• An ASCII title still downloads as summary-<title>.docx, notes-<title>.docx, or chat-<title>.docx. A non-ASCII title still uses the RFC 2231 header and the same info log. A failure of encode_rfc2231 still falls back to download-<id>.docx.
• A non-ASCII title or metadata line is still Arial with east-Asia Arial. An ASCII line still does not set that font. Bold, lists, and headings in the summary, notes, or chat body still come from process_markdown_to_docx. Inline code that is not ASCII still uses Consolas for east-Asia.
• GET /recording/<id>/download/transcript still returns text or markdown, with the header at src/api/recordings.py:346-354. A non-owner is still refused on all four download routes by test_download_endpoints_reject_non_owner.

Root Cause Analysis

The three Word routes were written as three copies of one download. download_summary_word (src/api/recordings.py:367-471) inlines the font and the response. download_notes_word (src/api/recordings.py:615-718) repeats them. download_chat_word (src/api/recordings.py:477-609) repeats them and then adds the message loop. process_markdown_to_docx (src/services/document.py:11-281) was the part that got shared. ensure_unicode_font stayed inside it (src/services/document.py:33-47), so the routes could not call it and grew their own copy.

download_transcript_with_template (src/api/recordings.py:206-360) is the nearby download and is not this path. It returns text or markdown, and its non-ASCII header puts an ASCII filename and a filename* value on the same line (src/api/recordings.py:350-354). The Word routes put only filename* on that branch (src/api/recordings.py:459-462). Sharing one header function across both shapes would change one of them.

Additional Context

as_attachment stays False. The summary and chat tests record that True on a BytesIO with no download name returns 500 (tests/test_cov_recordings_read.py:1704-1720, tests/test_cov_recordings_read.py:1755-1776). The helper is now the line those tests pin.

No user-guide page changes. The downloaded files look the same. No new setting belongs in config/env.asr.example.

This request does not add the Inquire conversation download. That is #555, and it is implemented after this one because it calls these helpers. This request also does not share the chat turn loop. That loop stays in download_chat_word (src/api/recordings.py:533-563) until the Inquire download is the second caller.

[murtaza-nasir]

Thank you for the detailed request. The heading font, the metadata paragraph and the Word file response are now shared functions in src/services/document.py, used by the summary, notes and chat downloads. The downloaded files are unchanged. This will be included in the next release.

[branch1337]

Thank you for reviewing and approving my suggestions.