# Meeting Transcriber - Customer Setup

This guide is for customers installing the generic Windows desktop build of Meeting
Transcriber. The installer does not include private endpoints, API keys, or company
Jira configuration. Each customer provides their own Microsoft, Azure OpenAI, and
optional Atlassian/Jira settings after installation.

## Feature Availability

Optional integrations can be disabled completely. When disabled, the app hides the
matching action buttons and Settings groups:

| Setting | Effect when `false` |
|---|---|
| `ONENOTE_ENABLED` | hides OneNote save actions and OneNote settings |
| `JIRA_ENABLED` | hides Jira ticket actions and Jira settings |

For a customer-specific installer, set these flags in the bundled configuration before
building. For an already installed app, an administrator or advanced user can set them
in the per-user file below and restart the app:

```text
%LOCALAPPDATA%\MeetingTranscriber\.env
```

Example:

```env
ONENOTE_ENABLED=true
JIRA_ENABLED=true
```

After restart, the matching Settings groups are visible and the remaining values can be
entered in the app.

## What You Need To Provide

### 1. Microsoft Entra App Registration

Meeting detection and optional OneNote publishing use Microsoft Graph with delegated
user permissions.

Create an app registration in your Microsoft Entra tenant:

1. Open Azure Portal > Microsoft Entra ID > App registrations > New registration.
2. Choose the supported account type appropriate for your organization.
3. In Authentication, add a Mobile and desktop applications redirect URI:

   ```text
   http://localhost
   ```

4. Enable public client flows.
5. Copy the Application (client) ID and Directory (tenant) ID.
6. Add delegated Microsoft Graph permissions as needed:

| Permission | Needed for | Consent |
|---|---|---|
| `Presence.Read` | Teams meeting detection | user |
| `Calendars.Read` | resolving the current meeting | user |
| `OnlineMeetings.Read` | resolving the Teams online meeting id | user |
| `OnlineMeetingArtifact.Read.All` | attendance report import | user |
| `OnlineMeetingTranscript.Read.All` | Teams transcript import with speaker names | admin |
| `Notes.ReadWrite` | saving transcripts to OneNote | user |
| `Sites.Read.All` | listing SharePoint-hosted OneNote notebooks | admin/user policy dependent |

Only `Presence.Read` is required for basic meeting detection. Other scopes are requested
when the matching feature is used or configured. Some organizations disable user consent;
in that case an administrator must grant consent even for user-consentable scopes.

### 2. Azure OpenAI Resource

Transcription and summaries use your Azure OpenAI resource. Provide:

| Setting | Meaning |
|---|---|
| `AOAI_ENDPOINT` | Azure OpenAI endpoint, e.g. `https://<resource>.openai.azure.com/` |
| `AOAI_API_KEY` | API key for that resource |
| `AOAI_API_VERSION` | API version, default `2024-10-21` |
| `TRANSCRIBE_MODELS` | ordered transcription deployment names |
| `LIVE_MODELS` | ordered realtime/live deployment names |
| `SUMMARY_MODELS` | ordered chat/summary deployment names |

Typical deployments:

| Deployment | Purpose |
|---|---|
| `gpt-4o-transcribe` | batch transcription and live transcription |
| `gpt-4o` | summaries, cleanup, Jira ticket drafting |
| `gpt-4o-transcribe-diarize` | optional speaker diarization |
| `whisper` | optional fallback batch transcription |
| `gpt-realtime-whisper` | optional live transcription |
| `gpt-realtime-translate` | optional live translation |

A second Azure OpenAI connection can be configured with `AOAI_ENDPOINT_2`,
`AOAI_API_KEY_2`, and `AOAI_API_VERSION_2` for failover.

### 3. Optional Atlassian Jira Cloud OAuth App

Jira ticket creation is optional. The desktop build uses Atlassian OAuth 2.0 3LO
against Jira Cloud. It is not configured for Jira Server/Data Center.

If you want Jira integration, create your own OAuth 2.0 app in the Atlassian Developer
Console:

1. Open `https://developer.atlassian.com/console/myapps/`.
2. Create or select an OAuth 2.0 (3LO) app.
3. Register this callback URL exactly:

   ```text
   http://localhost:8765/jira/callback
   ```

4. Enable the scopes configured in `JIRA_SCOPES`:

   ```text
   read:jira-work write:jira-work read:servicedesk-request write:servicedesk-request manage:servicedesk-customer offline_access
   ```

5. Turn on Distribution/Sharing so users outside the app owner account can consent.
6. Copy the client ID and client secret.

The port `8765` is not required by Atlassian. It is the default local port used by the
desktop app. If you change `PORT`, then `JIRA_REDIRECT_URI` and the Atlassian callback
registration must change to the same port.

You also need Jira project information:

| Setting | Meaning |
|---|---|
| `JIRA_SITE` | your Jira Cloud site, e.g. `https://example.atlassian.net` |
| `JIRA_SERVICE_DESK_KEY` | service desk/project key |
| `JIRA_ISSUE_TYPE` | issue type, default `Service Request` |
| `JIRA_ORG_FIELD` | optional custom field id for organizations |
| `JIRA_SUMMARY_PREFIX` | optional prefix for generated ticket titles |

## Installation

1. Run the Windows installer provided by your distributor.
2. If Windows SmartScreen appears, follow your organization's software trust process.
   Managed devices may require IT allow-listing or a signed installer.
3. Start Meeting Transcriber from the Start menu.
4. Open Settings from the popup footer.
5. Enter your configuration values:
   - Microsoft Graph tenant and client IDs
   - Azure OpenAI endpoint, key, API version, and model deployment names
   - optional OneNote notebook/section names, if `ONENOTE_ENABLED=true`
   - optional Jira OAuth and project settings, if `JIRA_ENABLED=true`
6. Save settings.
7. Use Microsoft sign-in from Settings when prompted.
8. If Jira is enabled, use Connect Jira from the Jira dialog or Settings and approve the
   Atlassian consent screen.

Settings are stored per Windows user in:

```text
%LOCALAPPDATA%\MeetingTranscriber\.env
```

Recordings, transcripts, logs, and token caches are also stored under:

```text
%LOCALAPPDATA%\MeetingTranscriber\
```

Reinstalling the app does not normally remove this per-user data directory.

## First Test

1. Start or join a Teams meeting.
2. Confirm the tray popup changes from idle to recording.
3. End the meeting or press Stop manually.
4. Wait for transcription and summary generation to finish.
5. Open the local transcript folder from the popup.
6. Optionally save the transcript to OneNote.
7. Optionally create Jira tickets from the transcript.

## Troubleshooting

### Microsoft sign-in is blocked

If sign-in fails with Conditional Access errors such as `53003`, ask your Microsoft
administrator to allow this Entra app or adjust the policy. The recommended auth mode
for installed users is interactive browser sign-in.

### Jira callback does not work

Check that all three values match exactly:

```text
PORT=8765
JIRA_REDIRECT_URI=http://localhost:8765/jira/callback
Atlassian callback URL=http://localhost:8765/jira/callback
```

Also confirm the Atlassian app is distributed/shared and that every requested scope is
enabled on the Atlassian app.

### Azure OpenAI calls fail

Confirm the endpoint, key, API version, and deployment names. The deployment names in
the app must match the deployment names in Azure OpenAI, not just the model family names.

### No Teams transcript or attendee report appears

Attendance reports are only available for meetings you organized and only after the
meeting session has ended. Teams transcript import requires the delegated
`OnlineMeetingTranscript.Read.All` permission, which usually needs admin consent.

## Security Notes

The current generic desktop build stores service configuration locally per user. If you
enter Azure OpenAI keys or Atlassian OAuth client secrets, they are available on that
machine to the installed user context. For broad enterprise distribution, prefer a
future server-backed deployment where secrets live on a managed backend instead of on
desktop clients.