Skip to content

Audio

This module provides API endpoints for streaming audio files.

stream_audio(document_id, request, file_service, user) async

Streams an audio file from the server.

This endpoint retrieves file information for a given document ID and returns a FileResponse to stream the audio file. It delegates Range handling to Starlette's FileResponse implementation.

Parameters:

  • document_id (UUID) –

    The unique identifier of the audio document to stream.

  • request (Request) –

    The FastAPI Request object.

  • file_service (Annotated[FileService, Depends(get_file_service)]) –

    The file service for handling file operations.

  • user (Annotated[Optional[User], Depends(get_optional_user)]) –

    The optionally authenticated user making the request.

Returns:

  • FileResponse ( FileResponse ) –

    A response object that streams the requested audio file.

Raises:

  • EntityNotFound –

    If the document or its associated connector is not found.

  • FunctionalError –

    If there is a functional issue with the request.

  • TechnicalError –

    If an unexpected error occurs during streaming.

Source code in app/api/v1/endpoints/audio.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
@router.get("/stream/{document_id}")
async def stream_audio(
    document_id: UUID,
    request: Request,
    file_service: Annotated[FileService, Depends(get_file_service)],
    user: Annotated[Optional[User], Depends(get_optional_user)],
) -> FileResponse:
    """
    Streams an audio file from the server.

    This endpoint retrieves file information for a given document ID and returns
    a FileResponse to stream the audio file. It delegates Range handling to
    Starlette's FileResponse implementation.

    Args:
        document_id: The unique identifier of the audio document to stream.
        request: The FastAPI Request object.
        file_service: The file service for handling file operations.
        user: The optionally authenticated user making the request.

    Returns:
        FileResponse: A response object that streams the requested audio file.

    Raises:
        EntityNotFound: If the document or its associated connector is not found.
        FunctionalError: If there is a functional issue with the request.
        TechnicalError: If an unexpected error occurs during streaming.
    """
    try:
        # P2: Strict Typing with Pydantic model
        stream_info: FileStreamingInfo = await file_service.get_file_for_streaming(document_id, current_user=user)

        # Access log audit could go here if needed
        # if user: logger.debug(f"Streaming {document_id} for {user.email}")

        return FileResponse(
            path=stream_info.file_path,
            media_type=stream_info.media_type,
            filename=stream_info.file_name,
            content_disposition_type="inline",
        )

    except (EntityNotFound, FunctionalError):
        # Already logged or handled at service level if needed
        raise
    except Exception as e:
        logger.error(f"Audio stream failed for {document_id}: {str(e)}", exc_info=True)
        raise TechnicalError(f"Audio stream failed: {str(e)}")