Troubleshooting - InfoAudio + MusicMaster via Nexus Server

Operational troubleshooting guide for the InfoAudio and MusicMaster integration through Nexus Server.

Source baseline: docs/InfoAudio_MusicMaster_Nexus_Troubleshooting.md

Language: American English

1. Purpose

This document consolidates the main diagnostic procedures for failures in the MusicMaster ↔ InfoAudio integration. Its goal is to reduce triage time in production and provide a practical path to identify whether the issue is in:

• connectivity to Nexus Server
• the IntegradorMusicMaster service
• the publishChangedHours and publishMetaData webhooks
• Player grid refresh
• real-time event reconciliation
• catalog or schedule synchronization

2. Quick Architecture View

Main flow:

1. MusicMaster publishes changes to the IntegradorMusicMaster service.
2. The service listens on the configured HTTP ports for:

• PortaPublishChangedHours
• PortaPublishMetaData

1. The service processes the payload and writes the update to the database.
2. On success, the service tries to notify the Player through the InfoAudioMusicMasterSync named pipe.
3. The Player receives the notification and triggers an immediate grid refresh.
4. In parallel, the Player also performs direct Nexus calls for reconciliation, replacement lookup, and schedule adjustments.

Relevant technical points in the current code:

• The Nexus endpoint is built from EnderecoNexusServer and PortaNexusServer in ConfiguracaoMusicMasterModel.
• The default listener ports are 8085 and 8086.
• The service creates HTTP listeners in IntegradorMMService.
• Notifications between service and Player use the InfoAudioMusicMasterSync named pipe.
• The Player initializes that listener in the ViewModelTelaProgramacao constructor.

3. Initial Validation Checklist

Before investigating specific symptoms, validate the following:

1. The IntegradorMusicMaster service is running.
2. The Nexus Server host and port are correct in the MusicMaster configuration.
3. The HTTP publish ports are not conflicting with another process.
4. Firewall rules and ACLs allow traffic between MusicMaster and the service host.
5. The Player is open in the programming module when immediate grid refresh is expected.
6. The InfoAudio database is reachable by both the service and the Player.
7. The MusicMaster station and field mappings are populated.
8. The integration points to the correct MusicMaster instance and not to an outdated environment.

Expected signals:

• The service logs that it started the HTTP listeners.
• The Player can validate Nexus connectivity.
• Schedule or metadata changes made in MusicMaster appear in InfoAudio.

4. Critical Configuration

Most sensitive parameters:

• EnderecoNexusServer
• PortaNexusServer
• PortaPublishChangedHours
• PortaPublishMetaData
• IntervaloSincronizacaoMinutos
• Estacao
• Mapeamentos

Default values observed in code:

• PortaNexusServer: falls back to 8080 when invalid
• PortaPublishChangedHours: 8085
• PortaPublishMetaData: 8086

If any of these values is empty, incorrect, or points to the wrong station, the behavior may look like an intermittent failure when it is actually a configuration problem.

5. Troubleshooting Matrix

5.1 The Player cannot connect to Nexus Server

**Symptom**

• Connection test fails in the Player
• MusicMaster replacement lookup does not work
• Reconciliation is not sent

**Possible causes**

• Incorrect EnderecoNexusServer
• Incorrect PortaNexusServer
• Nexus Server is unavailable
• Firewall blocking
• Incorrect station configuration

**Where it appears in code**

• Informa.Player/Services/MusicMasterService.cs
• Informa.MusicMaster.Business/AcessoService.cs
• Informa.Player/ViewModel/ViewModelReprodutora.cs
• Informa.Player/ViewModel/ViewModelTelaProgramacao.cs

**How to validate**

1. Confirm the configured host and port.
2. Validate that Nexus responds to PingAsync.
3. Check whether the problem occurs only in the Player or also in the Windows service.
4. Verify that the loaded station configuration is the expected one.

**Recommended action**

• Correct the Nexus endpoint and port.
• Validate network connectivity between the InfoAudio host and the Nexus host.
• Restart the service only after confirming the network or configuration fix.

5.2 MusicMaster publishes changes, but InfoAudio does not receive them

**Symptom**

• Changes made in MusicMaster do not reach InfoAudio
• No effect after publishChangedHours or publishMetaData

**Possible causes**

• IntegradorMusicMaster service is stopped
• HTTP listener did not start
• Ports 8085 or 8086 are already in use
• Firewall blocking MusicMaster calls
• Empty or invalid payload

**Where it appears in code**

• Informa.MusicMaster.WindowsService/IntegradorMMService.cs
• Informa.MusicMaster.Plugin.Model/ConfiguracaoMusicMasterModel.cs

**How to validate**

1. Confirm that the service started the HTTP listeners.
2. Verify that the configured ports match the endpoints registered in MusicMaster.
3. Check whether the service is returning 200 OK or 500 Error.
4. Review logs with messages such as:

• Starting HTTP listeners on ports ...
• Receiving task: Publish changed hours
• Receiving task: Publish meta data
• Task completed: ...

**Recommended action**

• Correct the endpoint registration in MusicMaster.
• Open the required ports in the firewall.
• Remove port conflicts with other services.
• If the payload is empty, review the publish configuration in MusicMaster or Nexus.

5.3 The Player grid does not refresh right after a MusicMaster change

**Symptom**

• The database was updated, but the operator still sees the old schedule
• The change appears only later or after manual reload

**Possible causes**

• The service received the change, but the Player did not receive the pipe notification
• The Player does not currently have ViewModelTelaProgramacao active
• The pipe debounce discarded notifications that arrived too close together
• _sincronizandoProgMM or Busy blocked the immediate refresh

**Where it appears in code**

• Informa.MusicMaster.WindowsService/NotificadorPlayer.cs
• Informa.MusicMaster.WindowsService/IntegradorMMService.cs
• Informa.Player/ViewModel/ViewModelTelaProgramacao.cs

**How to validate**

1. Confirm that the service called NotificadorPlayer.
2. Confirm that the Player started the InfoAudioMusicMasterSync listener.
3. Check Player logs for [MM SYNC] messages.
4. Verify whether the Player was in synchronization mode or busy at that time.

**Recommended action**

• Ensure the Player is open with the programming module loaded.
• If the pipe fails, force a manual refresh and check whether the Player restarted or the pipe broke.
• If the behavior is recurrent, treat it as an IPC issue between the service and the Player.

**Note**

This was historically an important issue, and there is already dedicated material in docs/MusicMaster-BugFix-GridDesatualizado.md.

5.4 Metadata changes in MusicMaster, but title or artist do not update in InfoAudio

**Symptom**

• The grid or catalog still shows old metadata
• The item exists, but the displayed text does not update

**Possible causes**

• publishMetaData did not reach the service
• Catalog import partially failed
• The Player did not receive or process the immediate notification
• The database changed, but the UI did not reload the affected item

**How to validate**

1. Confirm receipt of Publish meta data.
2. Verify that the service responded successfully.
3. Validate in the database that the metadata was persisted.
4. Reopen or reload the screen to separate persistence issues from visual refresh issues.

**Recommended action**

• If the database did not change, investigate catalog synchronization.
• If the database changed and the UI did not, investigate the pipe and grid refresh behavior.

5.5 Music replacement or schedule action fails

**Symptom**

• Shuffle or replacement cannot find songs
• add, move, or drop have no effect
• The item returns to its previous state

**Possible causes**

• Missing or outdated IdExterno
• Nexus connectivity failure
• ReconcileElementsAsync returned an error
• Race condition while updating IdExterno

**Where it appears in code**

• Informa.Player/Services/MusicMasterService.cs
• Informa.Player/ViewModel/ViewModelGrid.cs
• Informa.Player/ViewModel/ViewModelPlayer.cs
• Informa.Player/ViewModel/ViewModelReprodutora.cs
• Informa.Player/ViewModel/ViewModelTelaProgramacao.cs
• Informa.MusicMaster.Business/ProgramacaoServiceNova.cs

**How to validate**

1. Check whether the item has IdExterno.
2. Review logs before and after sending the request to Nexus.
3. Confirm whether a new historyId was returned for add operations.
4. Compare whether the local IdExterno was updated after the response.

**Recommended action**

• Reimport or resynchronize the affected block when there is suspicion of an invalid historyId.
• If the problem is recurrent for specific items, treat it as a linkage divergence between InfoAudio and MusicMaster.

5.6 Songs are being duplicated in MusicMaster

**Symptom**

• The MusicMaster catalog starts showing duplicate copies of the same song
• Deletions made in MusicMaster "come back" later

**Possible causes**

• MusicMaster removed the song, but InfoAudio interpreted the absence as a signal to re-export it
• Catalog fallback or individual lookup failed and the item was treated as missing
• There was no reliable exported-state tracking in the old flow

**Where it appears in supporting material**

• docs/MusicMaster-BugFix-Duplicacao.md
• docs/MusicMaster-Plano-Melhorias-V3.md

**How to validate**

1. Identify whether the song was deleted directly in MusicMaster before duplication began.
2. Verify whether the next InfoAudio -> MusicMaster sync cycle re-exported the song.
3. Compare cutId, songId, and synchronization timestamps.

**Recommended action**

• Treat this as a catalog synchronization incident.
• Avoid deleting songs directly in MusicMaster without validating the active synchronization policy.
• Verify whether the production version already contains the documented duplication fix.

5.7 The service seems to work, but there are silent and intermittent failures

**Symptom**

• Some changes synchronize and others do not
• There is no clear pattern
• Operations notices divergence, but logs are insufficient

**Possible causes**

• Swallowed exceptions in parts of the integration
• Fire-and-forget flows with unobserved failures
• No retry policy
• Race conditions

**Where it appears in supporting material**

• docs/MusicMaster-Plano-Melhorias-V3.md

**How to validate**

1. Check for windows of network or Nexus unavailability.
2. Correlate the incident time with reconciliation or synchronization activity.
3. Look for divergence between what the operator did and what MusicMaster recorded.

**Recommended action**

• Treat this as a structural limitation of the current integration.
• Increase observability before concluding that the issue is operator error.
• If possible, capture service, Player, and Nexus logs from the same time window.

5.8 playStart is sent, but execution end is not reflected in MusicMaster

**Symptom**

• MusicMaster records the start of playback, but not the end
• RunTime or end-of-play history remains incomplete

**Likely cause**

• playEnd is commented out in the Player

**Where it appears in code**

• Informa.Player/ViewModel/ViewModelPlayer.cs

**Impact**

• MusicMaster may not receive end-of-play confirmation.

**Recommended action**

• Do not treat this as an operational failure before confirming the expected behavior for the environment.
• Validate with the technical team whether the installation intentionally keeps playEnd disabled or whether this is still an unresolved limitation.

**Note**

docs/MusicMaster-Plano-Melhorias-V3.md treats this as a known issue and recommends safe reactivation only after validation.

5.9 The Windows service updates data, but the Player does not reflect it until restart

**Symptom**

• The service receives webhooks and processes them correctly
• The Player shows the change only after restart or a strong manual refresh

**Possible causes**

• Failure in named pipe communication
• ViewModelTelaProgramacao did not start the listener
• The immediate refresh was blocked by Busy or _sincronizandoProgMM

**How to validate**

1. Look for the log entry [MM SYNC] Notificação recebida via pipe.
2. If it is missing, the pipe did not deliver the message.
3. If it exists, verify whether it was followed by Disparando atualização imediata do grid.

**Recommended action**

• Restart the Player when pipe delivery is broken.
• If the issue persists, review the IPC mechanism in that environment.

5.10 Periodic synchronization runs, but it is too slow or impacts operations

**Symptom**

• Slow synchronization
• Long processing windows
• Divergence under high volume

**Possible causes**

• Large catalog
• Repetitive Nexus calls
• No intelligent retry or concurrency control
• Legacy infrastructure dependency

**How to validate**

1. Measure periodic synchronization duration.
2. Compare the change volume against the sync window.
3. Observe whether the service returns to normal state or keeps accumulating delay.

**Recommended action**

• Adjust the operational synchronization window.
• Treat large-volume cases as capacity issues, not only as bugs.
• Review the improvement plan when this becomes recurrent in larger broadcasters.

6. Layered Triage Flow

When an incident happens, follow this sequence:

1. Confirm that MusicMaster actually emitted the expected change.
2. Confirm that IntegradorMusicMaster was active.
3. Confirm that the webhook reached the correct port.
4. Confirm that the service processed the payload successfully.
5. Confirm that the database reflects the change.
6. Confirm that the pipe notified the Player.
7. Confirm that the Player refreshed the grid.
8. If reconciliation is involved, confirm the Nexus response and the IdExterno update.

This order avoids wasting time debugging the UI when the failure is in the network, or debugging the service when the divergence is actually in the historyId linkage.

7. Relevant Technical Evidence

Files worth checking first during incidents:

• Informa.MusicMaster.WindowsService/IntegradorMMService.cs
• Informa.MusicMaster.WindowsService/NotificadorPlayer.cs
• Informa.MusicMaster.Plugin.Model/ConfiguracaoMusicMasterModel.cs
• Informa.Player/Services/MusicMasterService.cs
• Informa.Player/ViewModel/ViewModelTelaProgramacao.cs
• Informa.Player/ViewModel/ViewModelPlayer.cs
• Informa.Player/ViewModel/ViewModelReprodutora.cs
• Informa.Player/ViewModel/ViewModelGrid.cs
• Informa.MusicMaster.Business/ProgramacaoServiceNova.cs
• Informa.MusicMaster.Business/SincronizacaoService.cs

Supporting documents:

• docs/MusicMaster-Plano-Melhorias-V3.md
• docs/MusicMaster-BugFix-Duplicacao.md
• docs/MusicMaster-BugFix-GridDesatualizado.md
• docs/CODEX_Docs/InfoAudio_Installation_and_Configuration_Guide_en-US.md

8. Known Limitations

The current state of the integration still carries structural risks already documented elsewhere:

• lack of robust retry across the stack
• possibility of silent failures
• strong dependency on IdExterno/historyId
• mixed synchronous and asynchronous flows
• history of race conditions in synchronization and schedule refresh

This means some production incidents may be real even when the first available log does not immediately prove it.

9. Operational Recommendations

• Standardize collection of service, Player, and Nexus logs within the same time window.
• Always record which station and which Nexus endpoint were configured at the time of the incident.
• In schedule divergence cases, verify the database and the pipe before blaming the UI.
• In replacement or reconciliation failures, verify IdExterno before taking corrective action.
• Avoid manual actions in MusicMaster that conflict with the synchronization policy unless a runbook explicitly allows them.

10. Field Summary

If you need to summarize the troubleshooting guidance quickly:

• If nothing synchronizes, start with Nexus and the IntegradorMusicMaster service.
• If the database updates but the screen does not, investigate the InfoAudioMusicMasterSync pipe.
• If replacement or reconciliation fails, suspect IdExterno/historyId.
• If duplicates appear, review the InfoAudio -> MusicMaster flow and the catalog duplication fix.
• If the behavior is intermittent, consider the known structural limitations of the integration.